Getting started

These GET endpoints read the authenticated account only. Main accounts do not inherit access to subaccount data, and administrators can query only themselves. Use a system access token, which is different from a model API key.

Get a system access token

Sign in to the console and generate a token under "System Access Token" in Settings. Regeneration invalidates the previous token, so update existing integrations. These queries are read-only, but the token retains its existing permissions on legacy endpoints; it is not a strictly read-only credential.

Send exactly one Authorization header. Cookies, URL credentials, model API keys, Agent tokens, and MCP tokens cannot replace it. X-User-Id is not required. Optional X-Locale accepts en, zh, zh-TW, ja, ko, and ru; otherwise account preferences and language negotiation apply.

curl --request GET \
  --url 'https://toapis.com/api/v1/account' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'

Responses and amounts

Success uses HTTP 200, code=0, and message="". Errors retain their HTTP status and use a numeric code. Branch on HTTP status and code, not the localized message. IDs and amounts are strings; timestamps use RFC 3339 with a timezone. Unknown or inapplicable fields are null where the contract allows it.

Balance and usage return USD and credits from the same quota snapshot. Use the returned credits_per_usd; do not hard-code a legacy balance conversion rate. Payment amounts retain their original currency and are separate from credits.

Responses include Cache-Control: private, no-store and X-Request-Id. The request ID identifies this query, not the original generation request referenced by a usage record.

{"code": 0, "message": "", "data": {"items": [], "has_more": false, "next_cursor": null, "meta": {}}}

Pagination and time ranges

Lists return data.items, has_more, next_cursor, and meta. Empty results use []; the final cursor is null. Pass next_cursor unchanged as cursor, keep the same filters, and restart when they change. Do not parse cursors. Total counts are not computed by default.

Ranges use UTC half-open intervals [from,to). Boundaries for second-resolution storage round upward. Supply from and to together; usage always requires both. Tasks default to the last 24 hours with a 31-day maximum. Top-ups and invoices default to 31 days with a 366-day maximum. Default ranges freeze on the first page and can stay omitted on subsequent pages. Unknown parameters, repeated scalars, and malformed escapes return 400.

Rate limits and errors

The shared user budget is 120 requests/minute. Usage summaries have an additional 6/minute budget; invoice lists and details share a separate 6/minute budget. On 429, follow Retry-After with jitter. Without Redis, light reads use per-node budgets of 30/minute per IP bucket and 30/minute per user; summaries and invoices return 503.

{
  "code": 10004,
  "message": "Invalid query parameters.",
  "data": {
    "param": "limit",
    "request_id": "request_example_query"
  }
}

Data scope

Usage is a mutable consumption-log snapshot. Settlement and refunds can change old records, so it is not a complete net-spend ledger. Tasks expose persisted metadata and confirmed billing only, without results, upstream polling, settlement, or refunds. Top-ups exclude manual gifts and standalone offline refunds. Invoices cover only the currently verified Stripe Customer.

Existing endpoints

Token balance, user balance, and token creation retain their existing contracts. This group uses a system access token and code/message/data responses. Account task queries do not replace generation-result endpoints.