Get usage summary | ToAPIs Documentation

GET

/api/v1/account/usage/summary

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.

group_bystringquerydefault: day

Group by day, model, or API key.

Constraints: day, model, api_key; Default: day.

timezonestringquerydefault: UTC

Accepted only with group_by=day. Other groupings return meta.timezone=null.

Constraints: UTC, Asia/Shanghai; Default: UTC.

requestExample

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

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[].daystring

Date bucket returned only for group_by=day, using the requested timezone. Format: YYYY-MM-DD.

data.items[].modelstring

Model bucket, returned only for group_by=model.

data.items[].api_key_idstring | null

API key bucket, returned only for group_by=api_key. Records without a key use the null bucket.

data.items[].record_countinteger

Number of consumption-log rows in the group, not a guaranteed complete request count.

data.items[].recorded_cost_usdstring

Sum 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_creditsstring

Sum of current logged credits in this group. Returned as a decimal string to preserve precision.

data.items[].input_tokensinteger

Sum of logged input tokens in this group.

data.items[].output_tokensinteger

Sum of logged output tokens in this group.

data.items[].unknown_phase_record_countinteger

Log rows in the group whose billing phase is unknown.

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.

data.meta.group_bystring

Grouping dimension used for this summary.

data.meta.timezonestring | null

Timezone for day buckets; null when grouping by model or API key.

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