Usage

Get usage

Aggregate settled prompts and conversions by completion time. Queued, running, and paused work is excluded. Totals reconcile to historical receipts, not current rates. Filters combine with AND; rows sort by UTC bucket and dimensions. The default window is the last 30 days.

Reports return at most 1,000 rows without pagination. Larger results return 422; narrow the range or use fewer groups/coarser buckets. Queries time out after five seconds with 503. Customer metadata expires with job content: metadata filters then stop matching and metadata dimensions become null, while account totals remain. Store job-to-customer mappings locally for long-term attribution. Model/provider dimensions describe admitted configuration, including deterministic conversions, rather than proving inference occurred. Unknown, empty, or repeated parameters return 400; empty metadata filter values are allowed.

GET

usage

Aggregate settled account usage and customer charges

curl --request GET \
  --url https://revise.io/api/v1/usage \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://revise.io/api/v1/usage', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://revise.io/api/v1/usage",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://revise.io/api/v1/usage"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://revise.io/api/v1/usage")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "start": "2026-09-06T00:00:00Z",
  "end": "2026-09-08T00:00:00Z",
  "time_basis": "completed_at",
  "bucket": "day",
  "group_by": [
    "metadata.customer"
  ],
  "totals": {
    "request_count": 5,
    "tool_cpu_seconds": "5.000000",
    "inference_usage": {
      "input_tokens": 6000,
      "cached_input_tokens": 2000,
      "cache_creation_input_tokens": 0,
      "output_tokens": 1000,
      "web_search_requests_by_unit": {
        "calls": 5,
        "queries": 0,
        "grounded_prompts": 0
      }
    },
    "cost": {
      "total_usd": "0.550000000",
      "itemized": {
        "base_fee_usd": "0.250000000",
        "cpu_fee_usd": "0.250000000",
        "inference_fee_usd": "0.050000000"
      }
    }
  },
  "data": [
    {
      "bucket_start": "2026-09-06T00:00:00Z",
      "bucket_end": "2026-09-07T00:00:00Z",
      "dimensions": {
        "metadata.customer": "acme"
      },
      "request_count": 2,
      "tool_cpu_seconds": "2.000000",
      "inference_usage": {
        "input_tokens": 2400,
        "cached_input_tokens": 800,
        "cache_creation_input_tokens": 0,
        "output_tokens": 400,
        "web_search_requests_by_unit": {
          "calls": 2,
          "queries": 0,
          "grounded_prompts": 0
        }
      },
      "cost": {
        "total_usd": "0.220000000",
        "itemized": {
          "base_fee_usd": "0.100000000",
          "cpu_fee_usd": "0.100000000",
          "inference_fee_usd": "0.020000000"
        }
      }
    },
    {
      "bucket_start": "2026-09-07T00:00:00Z",
      "bucket_end": "2026-09-08T00:00:00Z",
      "dimensions": {
        "metadata.customer": "acme"
      },
      "request_count": 3,
      "tool_cpu_seconds": "3.000000",
      "inference_usage": {
        "input_tokens": 3600,
        "cached_input_tokens": 1200,
        "cache_creation_input_tokens": 0,
        "output_tokens": 600,
        "web_search_requests_by_unit": {
          "calls": 3,
          "queries": 0,
          "grounded_prompts": 0
        }
      },
      "cost": {
        "total_usd": "0.330000000",
        "itemized": {
          "base_fee_usd": "0.150000000",
          "cpu_fee_usd": "0.150000000",
          "inference_fee_usd": "0.030000000"
        }
      }
    }
  ]
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

See usage reports for integration guidance.

TypeScript

import { ReviseClient } from "@reviseio/api";

const revise = new ReviseClient({ apiKey: process.env.REVISE_API_KEY! });
const result = await revise.usage.get({ start: "2026-09-01T00:00:00Z", end: "2026-10-01T00:00:00Z" });

Authorizations

Authorization

string

header

required

Revise API key from https://revise.io/console/api-keys. Send Authorization: Bearer .

Query Parameters

start

string<date-time>

Inclusive completion time. Defaults to 30 days before end. RFC3339 timezone required.

end

string<date-time>

Exclusive completion time. Defaults to now. Range must be positive and at most 366 days; hourly ranges at most 31 days.

bucket

enum<string>

default:day

UTC calendar buckets, or no time bucketing. Empty time buckets are omitted.

Available options:

hour,

day,

month,

none

group_by

string

Comma-separated distinct dimensions, maximum three: api_key_id, provider, model, status, document_access, pricing_version, metadata.KEY (KEY 1–64 bytes). Missing values form null groups. Example: api_key_id,metadata.customer.

status

enum<string>

Available options:

succeeded,

failed,

cancelled

conversation_id

string

Exact conv_ ID.

api_key_id

string

Exact key_ ID of the submitting key. Older unattributed prompts do not match.

metadata

object

Exact AND matches, e.g. metadata[customer]=Acme. Keys up to 64 bytes; values up to 512 bytes.

Show child attributes

provider

enum<string>

Exact requested provider. Gemini uses the public name gemini.

Available options:

openai,

anthropic,

xai,

gemini

model

string

Exact requested model ID; use with provider to disambiguate.

Maximum string length: 256

document_access

enum<string>

Exact admitted document permission; not inferred from tool behavior.

Available options:

read,

comment,

edit

pricing_version

string

Exact pricing version pinned at admission.

Maximum string length: 256

Response

Complete filtered usage report

start

string<date-time>

required

Example:

"2026-09-06T00:00:00Z"

end

string<date-time>

required

Example:

"2026-09-08T00:00:00Z"

time_basis

any

required

Example:

"completed_at"

bucket

enum<string>

required

Available options:

hour,

day,

month,

none

Example:

"day"

group_by

string[]

required

Maximum array length: 3

Example:

["metadata.customer"]

totals

object

required

Show child attributes

Example:

{
  "request_count": 5,
  "tool_cpu_seconds": "5.000000",
  "inference_usage": {
    "input_tokens": 6000,
    "cached_input_tokens": 2000,
    "cache_creation_input_tokens": 0,
    "output_tokens": 1000,
    "web_search_requests_by_unit": {
      "calls": 5,
      "queries": 0,
      "grounded_prompts": 0
    }
  },
  "cost": {
    "total_usd": "0.550000000",
    "itemized": {
      "base_fee_usd": "0.250000000",
      "cpu_fee_usd": "0.250000000",
      "inference_fee_usd": "0.050000000"
    }
  }
}

data

object[]

required

Maximum array length: 1000

Show child attributes

Example:

[
  {
    "bucket_start": "2026-09-06T00:00:00Z",
    "bucket_end": "2026-09-07T00:00:00Z",
    "dimensions": { "metadata.customer": "acme" },
    "request_count": 2,
    "tool_cpu_seconds": "2.000000",
    "inference_usage": {
      "input_tokens": 2400,
      "cached_input_tokens": 800,
      "cache_creation_input_tokens": 0,
      "output_tokens": 400,
      "web_search_requests_by_unit": {
        "calls": 2,
        "queries": 0,
        "grounded_prompts": 0
      }
    },
    "cost": {
      "total_usd": "0.220000000",
      "itemized": {
        "base_fee_usd": "0.100000000",
        "cpu_fee_usd": "0.100000000",
        "inference_fee_usd": "0.020000000"
      }
    }
  },
  {
    "bucket_start": "2026-09-07T00:00:00Z",
    "bucket_end": "2026-09-08T00:00:00Z",
    "dimensions": { "metadata.customer": "acme" },
    "request_count": 3,
    "tool_cpu_seconds": "3.000000",
    "inference_usage": {
      "input_tokens": 3600,
      "cached_input_tokens": 1200,
      "cache_creation_input_tokens": 0,
      "output_tokens": 600,
      "web_search_requests_by_unit": {
        "calls": 3,
        "queries": 0,
        "grounded_prompts": 0
      }
    },
    "cost": {
      "total_usd": "0.330000000",
      "itemized": {
        "base_fee_usd": "0.150000000",
        "cpu_fee_usd": "0.150000000",
        "inference_fee_usd": "0.030000000"
      }
    }
  }
]

Aggregate settled account usage and customer charges

curl --request GET \
  --url https://revise.io/api/v1/usage \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://revise.io/api/v1/usage', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://revise.io/api/v1/usage",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://revise.io/api/v1/usage"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://revise.io/api/v1/usage")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "start": "2026-09-06T00:00:00Z",
  "end": "2026-09-08T00:00:00Z",
  "time_basis": "completed_at",
  "bucket": "day",
  "group_by": [
    "metadata.customer"
  ],
  "totals": {
    "request_count": 5,
    "tool_cpu_seconds": "5.000000",
    "inference_usage": {
      "input_tokens": 6000,
      "cached_input_tokens": 2000,
      "cache_creation_input_tokens": 0,
      "output_tokens": 1000,
      "web_search_requests_by_unit": {
        "calls": 5,
        "queries": 0,
        "grounded_prompts": 0
      }
    },
    "cost": {
      "total_usd": "0.550000000",
      "itemized": {
        "base_fee_usd": "0.250000000",
        "cpu_fee_usd": "0.250000000",
        "inference_fee_usd": "0.050000000"
      }
    }
  },
  "data": [
    {
      "bucket_start": "2026-09-06T00:00:00Z",
      "bucket_end": "2026-09-07T00:00:00Z",
      "dimensions": {
        "metadata.customer": "acme"
      },
      "request_count": 2,
      "tool_cpu_seconds": "2.000000",
      "inference_usage": {
        "input_tokens": 2400,
        "cached_input_tokens": 800,
        "cache_creation_input_tokens": 0,
        "output_tokens": 400,
        "web_search_requests_by_unit": {
          "calls": 2,
          "queries": 0,
          "grounded_prompts": 0
        }
      },
      "cost": {
        "total_usd": "0.220000000",
        "itemized": {
          "base_fee_usd": "0.100000000",
          "cpu_fee_usd": "0.100000000",
          "inference_fee_usd": "0.020000000"
        }
      }
    },
    {
      "bucket_start": "2026-09-07T00:00:00Z",
      "bucket_end": "2026-09-08T00:00:00Z",
      "dimensions": {
        "metadata.customer": "acme"
      },
      "request_count": 3,
      "tool_cpu_seconds": "3.000000",
      "inference_usage": {
        "input_tokens": 3600,
        "cached_input_tokens": 1200,
        "cache_creation_input_tokens": 0,
        "output_tokens": 600,
        "web_search_requests_by_unit": {
          "calls": 3,
          "queries": 0,
          "grounded_prompts": 0
        }
      },
      "cost": {
        "total_usd": "0.330000000",
        "itemized": {
          "base_fee_usd": "0.150000000",
          "cpu_fee_usd": "0.150000000",
          "inference_fee_usd": "0.030000000"
        }
      }
    }
  ]
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

Getting started

Guides

REST reference

Get usage

TypeScript

Authorizations

Query Parameters

Response

​TypeScript

Authorizations

Query Parameters

Response

TypeScript