Pull Usage Records

Paginated consume usage records for the authenticated account. Data comes from consume-type usage logs and is intended for metering and reconciliation. This endpoint does not push data — callers pull on demand.

Base URL

https://api.autorouter.top — Production

Authentication

This endpoint requires a system access token (PAT) + Auto-Api-User. sk-xxx API Keys are not supported.

Header	Description
`Authorization`	System access token. Format: `Bearer {system_access_token}`. Generate it in Personal Center → Profile → Access Token. The `Bearer` prefix is optional.
`Auto-Api-User`	Current logged-in user ID. Must match the user that owns the token. Copy it from Personal Center → Profile → User ID.

After authentication, the response includes consume records for the entire account. Use token_name to narrow results to a specific token.

Endpoints

GET `/api/usage/records`

Pull usage records

🔐 PAT required (User permission)

Query Parameters

Name	Type	Required	Description
`start_timestamp`	integer	No	Start time (Unix seconds, `created_at >=`). `0` or omitted means no lower bound
`end_timestamp`	integer	No	End time (Unix seconds, `created_at <=`). `0` or omitted means no upper bound
`model_name`	string	No	Filter by model name (contains match)
`token_name`	string	No	Filter by token name (exact match)
`request_id`	string	No	Filter by request ID (exact match)
`p`	integer	No	Page number starting at `1`, default `1`
`page_size`	integer	No	Page size, default `10`, max `100`

Only consume-type records are returned; you do not pass a type parameter.

Responses

200: Success

Content-Type: application/json

401: Missing access token, or missing Auto-Api-User

An invalid access token still returns HTTP 200, with success set to false.

Response Fields

Top level

Field	Type	Description
`success`	boolean	Whether the request succeeded
`message`	string	Error message; empty string on success
`data`	object	Paginated payload

`data` pagination

Field	Type	Description
`page`	integer	Current page
`page_size`	integer	Page size
`total`	integer	Total matching records
`items`	array	Usage record list

`data.items[]` usage record

Field	Type	Description
`created_at`	integer	Settlement write time (Unix seconds)
`model_name`	string	Model name
`token_name`	string	Token name
`token_id`	integer	Token ID
`request_id`	string	Request ID
`amount`	number	Final amount due for this request in USD. For the same `request_id`, total consume amount minus total refund amount. Surcharge deltas are included and are not returned as separate rows. Full refunds are `0`.
`billing_status`	string	`charged`: amount is still due and counts toward reconciliation. `refunded`: the charge was fully returned, `amount` is `0`, and it does not count as usage
`prompt_tokens`	integer	Prompt tokens (`0` when not applicable)
`completion_tokens`	integer	Completion tokens (`0` when not applicable)
`resolution`	string	Video output resolution (e.g. `480p` / `720p` / `1080p` / `4k`). Empty when not video or not recorded
`duration_seconds`	number	Video duration in seconds. Omitted when absent
`is_task`	boolean	Whether this was an async generation task
`task_id`	string	Task ID. Omitted when absent

Notes

One settled consume record corresponds to one billable usage event. Aggregate hourly/daily by created_at and resolution on the caller side if needed.
resolution depends on billing-path instrumentation; some models or pricing modes may leave it empty — treat empty as unknown.
Reconcile by summing amount only where billing_status is charged. refunded means the charge was fully returned.
The time window filters the original consume time. Later refunds or surcharges still change that row's amount.

Request Examples

curl -X GET "https://api.autorouter.top/api/usage/records?start_timestamp=1717200000&end_timestamp=1717286400&page_size=50&p=1" \
  -H "Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN" \
  -H "Auto-Api-User: YOUR_USER_ID"

Response Examples

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 50,
    "total": 2,
    "items": [
      {
        "created_at": 1717234567,
        "model_name": "seedance-1.5-pro",
        "token_name": "prod-key",
        "token_id": 42,
        "request_id": "req_abc123",
        "amount": 0.3,
        "billing_status": "charged",
        "prompt_tokens": 0,
        "completion_tokens": 0,
        "resolution": "1080p",
        "duration_seconds": 5,
        "is_task": true,
        "task_id": "task_xyz"
      },
      {
        "created_at": 1717234000,
        "model_name": "gpt-4o",
        "token_name": "prod-key",
        "token_id": 42,
        "request_id": "req_def456",
        "amount": 0.0064,
        "billing_status": "charged",
        "prompt_tokens": 120,
        "completion_tokens": 80,
        "resolution": "",
        "is_task": false
      }
    ]
  }
}

Pull Usage Records

On this page