Get usage summary
Aggregate usage by day, model, or API key
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
Aggregates usage by a chosen dimension, for statistics by day, model, or key. group_by selects the grouping: day sorts by date ascending, model sorts by model name in UTF-8 byte order, and api_key returns the null group first then numeric IDs ascending.
Each aggregate item contains only its grouping fields. from/to are required per page with a maximum range of 31 days.
record_count is the number of log lines and unknown_phase_record_count is the number of lines whose billing phase cannot be confirmed. Neither equals complete request counts or final net spend. meta.timezone=null when group_by=model or api_key.
meta always declares records_mutable=true, refund_accounting=not_complete, consistency=eventual: settlement and refunds update old records and missing records do not mean zero consumption.
This endpoint, invoices, and pricing each have an additional limit of 6 requests per user per minute. Temporary service unavailability returns 503.
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.
group_bystringquerydefault: dayGroup by day, model, or API key.
Constraints: day, model, api_key; Default: day.
timezonestringquerydefault: UTCAccepted only with group_by=day. Other groupings return meta.timezone=null.
Constraints: UTC, Asia/Shanghai; Default: UTC.
Request examples
requestExample
curl --request GET \
--url 'https://api.toapis.com/api/v1/usage/summary?from=2026-11-01T00:00:00Z&to=2026-11-02T00:00:00Z&group_by=day&timezone=UTC' \
--header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'import requests
response = requests.get(
"https://api.toapis.com/api/v1/usage/summary",
headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
params={
"from": "2026-11-01T00:00:00Z",
"to": "2026-11-02T00:00:00Z",
"group_by": "day",
"timezone": "UTC"
},
timeout=30,
)
response.raise_for_status()
print(response.json())const url = new URL("https://api.toapis.com/api/v1/usage/summary");
url.search = new URLSearchParams({
"from": "2026-11-01T00:00:00Z",
"to": "2026-11-02T00:00:00Z",
"group_by": "day",
"timezone": "UTC"
}).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[].daystringDate bucket returned only for group_by=day, using the requested timezone. Format: YYYY-MM-DD.
data.items[].modelstringModel bucket, returned only for group_by=model.
data.items[].api_key_idstring | nullAPI key bucket, returned only for group_by=api_key. Records without a key use the null bucket.
data.items[].record_countintegerNumber of consumption-log rows in the group, not a guaranteed complete request count.
data.items[].recorded_cost_usdstringSum of current logged costs in USD for this group, not fully refund-adjusted net spend. Returned as a decimal string to preserve precision.
data.items[].recorded_creditsstringSum of current logged credits in this group. Returned as a decimal string to preserve precision.
data.items[].input_tokensintegerSum of logged input tokens in this group.
data.items[].output_tokensintegerSum of logged output tokens in this group.
data.items[].unknown_phase_record_countintegerLog rows in the group whose billing phase is unknown.
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.
data.meta.group_bystringGrouping dimension used for this summary.
data.meta.timezonestring | nullTimezone for day buckets; null when grouping by model or API key.
Response examples
responseExample
{
"code": 0,
"message": "",
"data": {
"items": [
{
"day": "2026-11-01",
"record_count": 2,
"recorded_cost_usd": "0.04",
"recorded_credits": "4",
"input_tokens": 2000,
"output_tokens": 400,
"unknown_phase_record_count": 0
}
],
"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",
"group_by": "day",
"timezone": "UTC"
}
}
}