List usage records | ToAPIs Documentation

GET

/api/v1/account/usage/records

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

See Getting started for authentication, pagination, and errors.

Behavior

The maximum range is 31 days. Records sort by creation time and ID descending. Summaries sort by day ascending, model UTF-8 byte order, or a null key bucket followed by numeric key ID ascending. Each group contains only its relevant day, model, or api_key_id field. record_count counts log rows, not complete request totals. billing_phase is pre_consumed, settled, or unknown, not final task accounting. trace refers to the original request, not this query. Optional trace and upstream total tokens can be null without clearing independent costs or input/output tokens. Metadata declares records_mutable=true, refund_accounting=not_complete, and consistency=eventual. Settlement and refunds can update old rows; no records do not prove zero spend. One-way syncing cannot guarantee capturing these changes.

Authentication

Authorizationstringheaderrequired

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

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.

requestExample

curl --request GET \
  --url 'https://toapis.com/api/v1/account/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://toapis.com/api/v1/account/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://toapis.com/api/v1/account/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.

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.

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
        },
        "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"
    }
  }
}