List usage records
Page through usage log rows for your account
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
AuthorizationstringheaderrequiredUse Bearer YOUR_SYSTEM_ACCESS_TOKEN. Model API keys are not accepted. X-User-Id is not required.
Request parameters
fromstringqueryrequiredInclusive start in RFC 3339 with a timezone. Provide together with to.
Constraints: date-time.
tostringqueryrequiredExclusive end in RFC 3339 with a timezone. Must be later than from.
Constraints: date-time.
api_key_idstringqueryDecimal 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]*$.
modelstringqueryExact model identifier. For usage, an empty string matches an empty model name.
Constraints: maxLength=255.
limitintegerquerydefault: 50Maximum number of items per page.
Constraints: minimum=1; maximum=100; Default: 50.
cursorstringqueryPass 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.
codeintegerNumeric result code; 0 means success.
messagestringResponse message; empty on success. Error messages are localized.
dataobjectResult object for this query.
data.itemsobject[]Records on this page; [] when empty.
data.items[].idstringConsumption log record ID. Returned as a decimal ID string.
data.items[].created_atstring | nullCreation time. RFC 3339 timestamp with a timezone. null when unknown or inapplicable.
data.items[].api_key_idstring | nullAssociated model API key ID; null when no key is associated.
data.items[].key_namestring | nullAPI key name recorded in the log. null when unknown or inapplicable.
data.items[].modelstringModel identifier.
data.items[].task_idstring | nullAssociated platform task ID. null when unknown or inapplicable.
data.items[].recorded_cost_usdstringCurrent logged cost in USD, not a fully refund-adjusted net-spend amount. Returned as a decimal string to preserve precision.
data.items[].recorded_creditsstringCurrent logged consumption amount in credits. Returned as a decimal string to preserve precision.
data.items[].billing_phasestringBilling phase recorded in the log, not the final task accounting state. Values: pre_consumed, settled, unknown.
data.items[].usageobjectLogged input, output, and provider-reported token counts.
data.items[].usage.input_tokensintegerInput token count recorded in the logs.
data.items[].usage.output_tokensintegerOutput token count recorded in the logs.
data.items[].usage.reported_total_tokensinteger | nullProvider-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 | nullCache-read token count recorded in the log.
data.items[].usage.cache_write_tokensinteger | nullTotal 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 | null5-minute cache-write tokens explicitly recorded in the log.
data.items[].usage.cache_write_1h_tokensinteger | null1-hour cache-write tokens explicitly recorded in the log.
data.items[].traceobject | nullTrace of the original generation request, not the ID of this query. null when unknown or inapplicable.
data.items[].trace.request_idstring | nullPlatform trace ID of the original generation request. null when unknown or inapplicable.
data.items[].trace.client_request_idstring | nullClient request ID recorded for the original generation request. null when unknown or inapplicable.
data.has_morebooleanWhether another page is available.
data.next_cursorstring | nullPass this cursor unchanged with the same filters. It is null on the last page.
data.metaobjectMetadata describing the source, query scope, and accounting basis.
data.meta.scopestringOwnership scope of the query: the authenticated account itself. Fixed value: "self".
data.meta.fromstringInclusive start of the query time range. RFC 3339 timestamp with a timezone.
data.meta.tostringExclusive end of the query time range. RFC 3339 timestamp with a timezone.
data.meta.time_basisstringTime filtering and date grouping use consumption-log creation time. Fixed value: "record_created_at".
data.meta.cost_basisstringCosts use current consumption-log row values, not a frozen final bill. Fixed value: "current_consume_log_amount".
data.meta.refund_accountingstringRefund-accounting completeness. not_complete means this is not a complete net-spend ledger. Fixed value: "not_complete".
data.meta.records_mutablebooleanWhether settlement or refunds can update records. Currently true.
data.meta.consistencystringConsistency model. eventual means records can be updated later. Fixed value: "eventual".
data.meta.consume_logging_enabledbooleanWhether consumption logging is enabled. No records do not prove zero charges.
data.meta.credits_per_usdstringCredits 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"
}
}
}