Get Usage Summary

GET/v1/billing

Returns account usage and cost summary rows for a date range.

Use this endpoint to build account-level usage reports. By default it returns a daily summary for the last 30 days.

Without member filters, results cover the currently authenticated account (the user behind the API key or JWT). Enterprise admins may pass sub_account_id or key_display to query usage for a tenant member or API key for charge allocation.

Authentication

Authorization Bearer

Send an API key (sk-...) or user JWT in the Authorization header.

Query Parameters

typeenum<string>

Usage query type.

groupenum<string>

Grouping granularity.

start_daystring

Start day in YYYY-MM-DD format. Defaults to 30 days before today UTC.

end_daystring

End day in YYYY-MM-DD format. Defaults to today UTC.

model_idinteger

Optional internal model id filter.

pageinteger

Page number, starting at 1.

page_sizeinteger

Page size from 1 to 200.

sub_account_idstring

Optional. Enterprise admin filter by member sub-account id (10 digits). Use @main for the enterprise admin's own usage. enterprise_admin only.

key_displaystring

Optional. Enterprise admin filter by API key display (key_prefix + key_hint, e.g. sk-token360-inf-****). enterprise_admin only.

Enterprise allocation (member / API key)

Default: normal users, enterprise members, and enterprise admins (without filters) see their own usage.
Enterprise admin: pass sub_account_id or key_display to summarize usage for one tenant member or one API key.
Mutually exclusive: do not pass sub_account_id and key_display together.
Main account placeholder: when filtering the enterprise admin's own usage by member id, use sub_account_id=@main.
key_display format: same as the enterprise console and audit lists — key_prefix concatenated with key_hint (not the full secret).

Response

codeinteger

Response status code.

dataobject[]

Usage summary rows.

data.periodstring

Grouped period label.

data.hour_id_startstring

Start timestamp for the group.

data.hour_id_endstring

End timestamp for the group.

data.wallet_amountnumber

Amount charged to wallet balance.

data.credit_amountnumber

Amount charged to credit balance.

data.total_amountnumber

Total charged amount.

data.input_tokensstring

Input token count.

data.output_tokensstring

Output token count.

data.request_numstring

Number of billed requests.

data.image_countstring

Generated image count.

data.video_secondsnumber

Generated video seconds.

data.model_idstring | null

Model id when grouped by model.

Error Handling

401 / unauthenticated: missing or invalid Authorization.
INVALID_BILLING_USAGE_PAGINATION: page or page_size is out of range.
NOT_ENTERPRISE_ADMIN: a non-enterprise-admin caller passed sub_account_id or key_display.
INVALID_BILLING_FILTER: both sub_account_id and key_display were provided.
Member / key not found: sub_account_id or key_display cannot be resolved within the tenant.

Solicitar

Shell

1curl -sS "https://api.token360.ai/v1/billing?type=SUMMARY&group=DAY&page=1&page_size=2" \
2  -H "Authorization: Bearer sk-your-api-key"

Request (enterprise admin · by member)

Shell

1curl -sS "https://api.token360.ai/v1/billing?group=DAY&sub_account_id=1447301551" \
2  -H "Authorization: Bearer sk-enterprise-admin-key"

Request (enterprise admin · by API key)

Shell

1curl -sS "https://api.token360.ai/v1/billing?group=DAY&key_display=sk-token360-inf-5lugh" \
2  -H "Authorization: Bearer sk-enterprise-admin-key"

Respuesta

JSON

1{
2  "code": 200,
3  "data": [
4    {
5      "hour_id_end": "1780099200",
6      "hour_id_start": "1780012800",
7      "image_count": "0",
8      "input_tokens": "0",
9      "model_id": null,
10      "output_tokens": "0",
11      "period": "2026-05-29",
12      "request_num": "2",
13      "total_amount": 0.0002068,
14      "video_seconds": 0,
15      "credit_amount": 0e-10,
16      "wallet_amount": 0.0002068
17    },
18    {
19      "hour_id_end": "1779926400",
20      "hour_id_start": "1779840000",
21      "image_count": "0",
22      "input_tokens": "0",
23      "model_id": null,
24      "output_tokens": "0",
25      "period": "2026-05-27",
26      "request_num": "1",
27      "total_amount": 0.7163708,
28      "video_seconds": 0,
29      "credit_amount": 0e-10,
30      "wallet_amount": 0.7163708
31    }
32  ],
33  "msg": "success",
34  "serviceCode": null,
35  "traceId": "trace_example_123"
36}

¿Ha sido de ayuda?