Query Token Usage

curl --request GET \
  --url 'https://toapis.com/api/usage/tokens/requests?start_timestamp=1759708800&end_timestamp=1760313600&page_size=100' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-User-Id: YOUR_USER_ID'

curl --request GET \
  --url 'https://toapis.com/api/usage/tokens/summary?start_timestamp=1759708800&end_timestamp=1760313600&token_id=45' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-User-Id: YOUR_USER_ID'

import requests

API_BASE = 'https://toapis.com'
headers = {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'X-User-Id': 'YOUR_USER_ID',
}
params = {
    'start_timestamp': 1759708800,
    'end_timestamp': 1760313600,
    'page_size': 100,
}

while True:
    r = requests.get(f'{API_BASE}/api/usage/tokens/requests',
                     headers=headers, params=params)
    body = r.json()
    for row in body['data']:
        print(row['created_at'], row['token_name'], row['model_name'],
              row['prompt_tokens'], row['completion_tokens'],
              row['cache_tokens'], row['cost_usd'])
    if not body['meta']['has_more']:
        break
    params['cursor'] = body['meta']['next_cursor']

{
  "success": true,
  "data": [
    {
      "log_id": 10241024,
      "created_at": 1760001234,
      "token_id": 45,
      "token_name": "prod-backend",
      "model_name": "gpt-5.1",
      "task_id": "",
      "prompt_tokens": 148320,
      "completion_tokens": 2198,
      "cache_tokens": 96000,
      "cache_creation_tokens": 0,
      "reported_total_tokens": 150518,
      "total_tokens": 150518,
      "billing_phase": "settled",
      "quota": 7839,
      "cost_usd": "0.015678"
    }
  ],
  "meta": {
    "start_timestamp": 1759708800,
    "end_timestamp": 1760313600,
    "page_size": 100,
    "has_more": true,
    "next_cursor": "eyJraW5kIjoicmVxdWVzdHMiLC4uLn0",
    "cost_basis": "consume_log_quota",
    "currency": "USD",
    "quota_per_usd": "500000",
    "consume_logging_enabled": true,
    "refunds_included": false,
    "total_tokens_basis": "logged_prompt_plus_completion"
  }
}

{
  "success": true,
  "data": [
    {
      "token_id": 45,
      "request_count": 87,
      "prompt_tokens": 3200400,
      "completion_tokens": 150220,
      "total_tokens": 3350620,
      "quota": 401234,
      "cost_usd": "0.802468"
    }
  ],
  "meta": {
    "start_timestamp": 1759708800,
    "end_timestamp": 1760313600,
    "page_size": 50,
    "has_more": false,
    "next_cursor": "",
    "cost_basis": "consume_log_quota",
    "currency": "USD",
    "quota_per_usd": "500000",
    "consume_logging_enabled": true,
    "refunds_included": false,
    "total_tokens_basis": "logged_prompt_plus_completion"
  }
}

{
  "success": false,
  "error": {
    "code": "unauthorized",
    "message": "user authentication is required"
  }
}

{
  "success": false,
  "error": {
    "code": "invalid_query",
    "message": "time range must be positive and no longer than 31 days"
  }
}

{
  "success": false,
  "error": {
    "code": "query_timeout",
    "message": "usage query exceeded the time limit; use a shorter time range"
  }
}

GET

api

usage

tokens

requests

curl --request GET \
  --url 'https://toapis.com/api/usage/tokens/requests?start_timestamp=1759708800&end_timestamp=1760313600&page_size=100' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-User-Id: YOUR_USER_ID'

curl --request GET \
  --url 'https://toapis.com/api/usage/tokens/summary?start_timestamp=1759708800&end_timestamp=1760313600&token_id=45' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-User-Id: YOUR_USER_ID'

import requests

API_BASE = 'https://toapis.com'
headers = {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'X-User-Id': 'YOUR_USER_ID',
}
params = {
    'start_timestamp': 1759708800,
    'end_timestamp': 1760313600,
    'page_size': 100,
}

while True:
    r = requests.get(f'{API_BASE}/api/usage/tokens/requests',
                     headers=headers, params=params)
    body = r.json()
    for row in body['data']:
        print(row['created_at'], row['token_name'], row['model_name'],
              row['prompt_tokens'], row['completion_tokens'],
              row['cache_tokens'], row['cost_usd'])
    if not body['meta']['has_more']:
        break
    params['cursor'] = body['meta']['next_cursor']

{
  "success": true,
  "data": [
    {
      "log_id": 10241024,
      "created_at": 1760001234,
      "token_id": 45,
      "token_name": "prod-backend",
      "model_name": "gpt-5.1",
      "task_id": "",
      "prompt_tokens": 148320,
      "completion_tokens": 2198,
      "cache_tokens": 96000,
      "cache_creation_tokens": 0,
      "reported_total_tokens": 150518,
      "total_tokens": 150518,
      "billing_phase": "settled",
      "quota": 7839,
      "cost_usd": "0.015678"
    }
  ],
  "meta": {
    "start_timestamp": 1759708800,
    "end_timestamp": 1760313600,
    "page_size": 100,
    "has_more": true,
    "next_cursor": "eyJraW5kIjoicmVxdWVzdHMiLC4uLn0",
    "cost_basis": "consume_log_quota",
    "currency": "USD",
    "quota_per_usd": "500000",
    "consume_logging_enabled": true,
    "refunds_included": false,
    "total_tokens_basis": "logged_prompt_plus_completion"
  }
}

{
  "success": true,
  "data": [
    {
      "token_id": 45,
      "request_count": 87,
      "prompt_tokens": 3200400,
      "completion_tokens": 150220,
      "total_tokens": 3350620,
      "quota": 401234,
      "cost_usd": "0.802468"
    }
  ],
  "meta": {
    "start_timestamp": 1759708800,
    "end_timestamp": 1760313600,
    "page_size": 50,
    "has_more": false,
    "next_cursor": "",
    "cost_basis": "consume_log_quota",
    "currency": "USD",
    "quota_per_usd": "500000",
    "consume_logging_enabled": true,
    "refunds_included": false,
    "total_tokens_basis": "logged_prompt_plus_completion"
  }
}

{
  "success": false,
  "error": {
    "code": "unauthorized",
    "message": "user authentication is required"
  }
}

{
  "success": false,
  "error": {
    "code": "invalid_query",
    "message": "time range must be positive and no longer than 31 days"
  }
}

{
  "success": false,
  "error": {
    "code": "query_timeout",
    "message": "usage query exceeded the time limit; use a shorter time range"
  }
}

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.

Query per-request token consumption and cost across all of your API Keys, or filter to a single key
Input, output and cached token counts reported separately
Aggregated per-key totals via the summary endpoint
Cursor-based pagination, time window up to 31 days

These endpoints read your billing logs and return every billable request with its token breakdown and cost, plus a per-key rollup. They complement the Query Token Balance endpoint, which only returns the aggregate balance of one key.

Authorizations

string

required

These endpoints authenticate as your user account, not as an API Key.

Open Account Settings and click Generate Token under “System Access Token” to create an access token (not an sk- API key). Generating again invalidates the previous token.
Send it in the Authorization header together with your user ID:

Authorization: Bearer YOUR_ACCESS_TOKEN
X-User-Id: YOUR_USER_ID

Your numeric user ID is shown on the same settings page.

string

required

Your numeric user ID. Required alongside the access token.

Endpoints

GET /api/usage/tokens/requests   # per-request detail
GET /api/usage/tokens/summary    # per-key aggregate

Query Parameters

Both endpoints accept the same parameters. Unknown or repeated parameters are rejected with 422.

integer

required

Start of the time window, Unix timestamp in seconds (inclusive).

integer

required

End of the time window, Unix timestamp in seconds (exclusive). Must be after start_timestamp; the window may span at most 31 days.

integer

Optional. Restrict results to a single API Key by its numeric token ID. Omit to include all keys.

integer

default:"50"

Number of rows per page, 1–100.

string

Pagination cursor returned as meta.next_cursor by the previous response. Only valid for the same endpoint, time window and token_id filter that produced it.

Response

GET /api/usage/tokens/requests returns one row per billable request, newest first.

integer

Internal log ID of the request. Unique within the response.

integer

When the request was billed, Unix timestamp in seconds.

integer

ID of the API Key that made the request.

string

Name of the API Key.

string

Model that served the request.

string

Task ID for asynchronous requests (image/video generation). Empty for synchronous requests.

integer

Input tokens billed.

integer

Output tokens billed.

integer | null

Cached input tokens read (cache hits). null when the upstream did not report cache usage.

integer | null

Tokens written to cache. null when not reported.

integer | null

Total tokens as reported by the upstream provider, when available.

integer

prompt_tokens + completion_tokens.

string

pre_consumed, settled, or unknown when the log predates detailed billing metadata.

integer

Quota consumed, in the platform’s internal unit.

string

Cost in USD, converted as quota / quota_per_usd (see meta). Returned as a string to preserve precision.

GET /api/usage/tokens/summary returns one row per API Key, ordered by token_id.

integer

API Key ID.

integer

Number of billable requests in the window.

integer

Total input tokens for this key.

integer

Total output tokens for this key.

integer

prompt_tokens + completion_tokens.

integer

Total quota consumed by this key.

string

Total cost in USD for this key.

Meta

boolean

Whether another page exists.

string

Pass as cursor to fetch the next page. Empty when has_more is false.

string

Internal quota units per USD used for the cost_usd conversion.

boolean

Whether consumption logging is enabled. When false, responses may be empty.

boolean

Currently always false — refunded amounts are not deducted.

curl --request GET \
  --url 'https://toapis.com/api/usage/tokens/requests?start_timestamp=1759708800&end_timestamp=1760313600&page_size=100' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-User-Id: YOUR_USER_ID'

curl --request GET \
  --url 'https://toapis.com/api/usage/tokens/summary?start_timestamp=1759708800&end_timestamp=1760313600&token_id=45' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-User-Id: YOUR_USER_ID'

import requests

API_BASE = 'https://toapis.com'
headers = {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'X-User-Id': 'YOUR_USER_ID',
}
params = {
    'start_timestamp': 1759708800,
    'end_timestamp': 1760313600,
    'page_size': 100,
}

while True:
    r = requests.get(f'{API_BASE}/api/usage/tokens/requests',
                     headers=headers, params=params)
    body = r.json()
    for row in body['data']:
        print(row['created_at'], row['token_name'], row['model_name'],
              row['prompt_tokens'], row['completion_tokens'],
              row['cache_tokens'], row['cost_usd'])
    if not body['meta']['has_more']:
        break
    params['cursor'] = body['meta']['next_cursor']

{
  "success": true,
  "data": [
    {
      "log_id": 10241024,
      "created_at": 1760001234,
      "token_id": 45,
      "token_name": "prod-backend",
      "model_name": "gpt-5.1",
      "task_id": "",
      "prompt_tokens": 148320,
      "completion_tokens": 2198,
      "cache_tokens": 96000,
      "cache_creation_tokens": 0,
      "reported_total_tokens": 150518,
      "total_tokens": 150518,
      "billing_phase": "settled",
      "quota": 7839,
      "cost_usd": "0.015678"
    }
  ],
  "meta": {
    "start_timestamp": 1759708800,
    "end_timestamp": 1760313600,
    "page_size": 100,
    "has_more": true,
    "next_cursor": "eyJraW5kIjoicmVxdWVzdHMiLC4uLn0",
    "cost_basis": "consume_log_quota",
    "currency": "USD",
    "quota_per_usd": "500000",
    "consume_logging_enabled": true,
    "refunds_included": false,
    "total_tokens_basis": "logged_prompt_plus_completion"
  }
}

{
  "success": true,
  "data": [
    {
      "token_id": 45,
      "request_count": 87,
      "prompt_tokens": 3200400,
      "completion_tokens": 150220,
      "total_tokens": 3350620,
      "quota": 401234,
      "cost_usd": "0.802468"
    }
  ],
  "meta": {
    "start_timestamp": 1759708800,
    "end_timestamp": 1760313600,
    "page_size": 50,
    "has_more": false,
    "next_cursor": "",
    "cost_basis": "consume_log_quota",
    "currency": "USD",
    "quota_per_usd": "500000",
    "consume_logging_enabled": true,
    "refunds_included": false,
    "total_tokens_basis": "logged_prompt_plus_completion"
  }
}

{
  "success": false,
  "error": {
    "code": "unauthorized",
    "message": "user authentication is required"
  }
}

{
  "success": false,
  "error": {
    "code": "invalid_query",
    "message": "time range must be positive and no longer than 31 days"
  }
}

{
  "success": false,
  "error": {
    "code": "query_timeout",
    "message": "usage query exceeded the time limit; use a shorter time range"
  }
}

Notes

Only billable requests are listed. Failed requests that were not billed do not appear, and no per-request success flag is returned.
Cost reflects the quota recorded at billing time; it is not re-priced against the current catalog, and refunds are not deducted.
Raw API keys, channel, IP addresses and request/response content are never exposed by these endpoints.
cursor is bound to the endpoint, time window and token_id filter — do not reuse a cursor across different queries.
Queries time out after a few seconds; if you receive query_timeout, shorten the time window and retry.

Overview

Quick Start

Model Catalog

Chat API

Image API

Video API

Music API

Task Management

File Uploads

Account

FAQs

Authorizations

Endpoints

Query Parameters

Response

Meta

Notes

​Authorizations

​Endpoints

​Query Parameters

​Response

​Meta

​Notes

Authorizations

Endpoints

Query Parameters

Response

Meta

Notes