ToAPIsToAPIs
Usage

List usage records

Page through usage log rows for your account

GET
/api/v1/usage/records

Note for users in mainland China: Please use https://api.toapis.cn as the API endpoint (Base URL). Replace https://api.toapis.com with https://api.toapis.cn in the examples in this document.

See Access for authentication, pagination, and errors.

Behavior

Returns paginated usage details from consumption logs, for reconciliation or analyzing per-call costs. from/to are required on every page and the range is at most 31 days. Results are ordered by creation time and log ID descending.

api_key_id can only filter consumption of your own keys. Deleted keys do not affect historical records, and consumption without an associated key has api_key_id=null.

recorded_cost_usd/recorded_credits is the amount of the current log line and is not guaranteed to equal the final net cost. billing_phase is pre_consumed, settled, or unknown, describing the log line's billing stage rather than the task's final billing state.

trace belongs to the original generation request and is unrelated to this query's request ID.

meta always declares records_mutable=true, refund_accounting=not_complete, consistency=eventual.

That is, settlement and refunds update records you may have already read, missing records do not prove zero consumption, and if you only sync these records one-way into your own system you will not see later changes to old records.

Authentication

Authorizationstringheaderrequired

Use Bearer YOUR_SYSTEM_ACCESS_TOKEN. Model API keys are not accepted. X-User-Id is not required.

Request parameters

fromstringqueryrequired

Inclusive start in RFC 3339 with a timezone. Provide together with to.

Constraints: date-time.

tostringqueryrequired

Exclusive end in RFC 3339 with a timezone. Must be later than from.

Constraints: date-time.

api_key_idstringquery

Decimal string ID of your model API key. A key owned by someone else returns 404. Deleted keys can still filter your historical usage.

Constraints: pattern=^[1-9][0-9]*$.

modelstringquery

Exact model identifier. For usage, an empty string matches an empty model name.

Constraints: maxLength=255.

limitintegerquerydefault: 50

Maximum number of items per page.

Constraints: minimum=1; maximum=100; Default: 50.

cursorstringquery

Pass the previous next_cursor unchanged and keep the same filters. Restart when filters change.

Constraints: maxLength=2048.

Request examples

requestExample

curl --request GET \
  --url 'https://api.toapis.com/api/v1/usage/records?from=2026-11-01T00:00:00Z&to=2026-11-02T00:00:00Z&api_key_id=42&limit=20' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'
import requests

response = requests.get(
    "https://api.toapis.com/api/v1/usage/records",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    params={
        "from": "2026-11-01T00:00:00Z",
        "to": "2026-11-02T00:00:00Z",
        "api_key_id": "42",
        "limit": "20"
    },
    timeout=30,
)
response.raise_for_status()
print(response.json())
const url = new URL("https://api.toapis.com/api/v1/usage/records");
url.search = new URLSearchParams({
  "from": "2026-11-01T00:00:00Z",
  "to": "2026-11-02T00:00:00Z",
  "api_key_id": "42",
  "limit": "20"
}).toString();

const response = await fetch(url, {
  headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN" },
  signal: AbortSignal.timeout(30_000),
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());

Response fields

Examples use fictional data and assume credits_per_usd="100". Use the conversion rate returned by the API.

Results are in data.items. Paginate with has_more and next_cursor; the final cursor is null. No total count is returned.

codeinteger

Numeric result code; 0 means success.

messagestring

Response message; empty on success. Error messages are localized.

dataobject

Result object for this query.

data.itemsobject[]

Records on this page; [] when empty.

data.items[].idstring

Consumption log record ID. Returned as a decimal ID string.

data.items[].created_atstring | null

Creation time. RFC 3339 timestamp with a timezone. null when unknown or inapplicable.

data.items[].api_key_idstring | null

Associated model API key ID; null when no key is associated.

data.items[].key_namestring | null

API key name recorded in the log. null when unknown or inapplicable.

data.items[].modelstring

Model identifier.

data.items[].task_idstring | null

Associated platform task ID. null when unknown or inapplicable.

data.items[].recorded_cost_usdstring

Current logged cost in USD, not a fully refund-adjusted net-spend amount. Returned as a decimal string to preserve precision.

data.items[].recorded_creditsstring

Current logged consumption amount in credits. Returned as a decimal string to preserve precision.

data.items[].billing_phasestring

Billing phase recorded in the log, not the final task accounting state. Values: pre_consumed, settled, unknown.

data.items[].usageobject

Logged input, output, and provider-reported token counts.

data.items[].usage.input_tokensinteger

Input token count recorded in the logs.

data.items[].usage.output_tokensinteger

Output token count recorded in the logs.

data.items[].usage.reported_total_tokensinteger | null

Provider-reported total tokens; null when unknown, not synthesized from input and output counts.

All four cache fields are always present: null when unrecorded, invalid, or beyond the read budget, and 0 for an explicitly logged zero. Breakdowns and totals are not derived from each other. A zero in the log does not prove the provider reported zero either.

input_tokens keeps the log’s original semantics and is not guaranteed to include cache volume, so do not compute a hit rate by dividing cache reads by input. The summary endpoint does not aggregate cache fields yet.

data.items[].usage.cache_read_tokensinteger | null

Cache-read token count recorded in the log.

data.items[].usage.cache_write_tokensinteger | null

Total cache-write tokens recorded in the log, including the 5m and 1h breakdowns. Do not add the breakdowns again.

data.items[].usage.cache_write_5m_tokensinteger | null

5-minute cache-write tokens explicitly recorded in the log.

data.items[].usage.cache_write_1h_tokensinteger | null

1-hour cache-write tokens explicitly recorded in the log.

data.items[].traceobject | null

Trace of the original generation request, not the ID of this query. null when unknown or inapplicable.

data.items[].trace.request_idstring | null

Platform trace ID of the original generation request. null when unknown or inapplicable.

data.items[].trace.client_request_idstring | null

Client request ID recorded for the original generation request. null when unknown or inapplicable.

data.has_moreboolean

Whether another page is available.

data.next_cursorstring | null

Pass this cursor unchanged with the same filters. It is null on the last page.

data.metaobject

Metadata describing the source, query scope, and accounting basis.

data.meta.scopestring

Ownership scope of the query: the authenticated account itself. Fixed value: "self".

data.meta.fromstring

Inclusive start of the query time range. RFC 3339 timestamp with a timezone.

data.meta.tostring

Exclusive end of the query time range. RFC 3339 timestamp with a timezone.

data.meta.time_basisstring

Time filtering and date grouping use consumption-log creation time. Fixed value: "record_created_at".

data.meta.cost_basisstring

Costs use current consumption-log row values, not a frozen final bill. Fixed value: "current_consume_log_amount".

data.meta.refund_accountingstring

Refund-accounting completeness. not_complete means this is not a complete net-spend ledger. Fixed value: "not_complete".

data.meta.records_mutableboolean

Whether settlement or refunds can update records. Currently true.

data.meta.consistencystring

Consistency model. eventual means records can be updated later. Fixed value: "eventual".

data.meta.consume_logging_enabledboolean

Whether consumption logging is enabled. No records do not prove zero charges.

data.meta.credits_per_usdstring

Credits per 1 USD. Use this rate for conversion. Returned as a decimal string to preserve precision.

Response examples

responseExample

{
  "code": 0,
  "message": "",
  "data": {
    "items": [
      {
        "id": "9001",
        "created_at": "2026-11-01T08:00:00Z",
        "api_key_id": "42",
        "key_name": "Example Key",
        "model": "example-text-model",
        "task_id": null,
        "recorded_cost_usd": "0.02",
        "recorded_credits": "2",
        "billing_phase": "settled",
        "usage": {
          "input_tokens": 1000,
          "output_tokens": 200,
          "reported_total_tokens": 1200,
          "cache_read_tokens": 300,
          "cache_write_tokens": 200,
          "cache_write_5m_tokens": 150,
          "cache_write_1h_tokens": 50
        },
        "trace": {
          "request_id": "request_example_01",
          "client_request_id": "client_example_01"
        }
      }
    ],
    "has_more": false,
    "next_cursor": null,
    "meta": {
      "scope": "self",
      "from": "2026-11-01T00:00:00Z",
      "to": "2026-11-02T00:00:00Z",
      "time_basis": "record_created_at",
      "cost_basis": "current_consume_log_amount",
      "refund_accounting": "not_complete",
      "records_mutable": true,
      "consistency": "eventual",
      "consume_logging_enabled": true,
      "credits_per_usd": "100"
    }
  }
}