Cost and statistics API
Final charges, balance and usage history.
Cost in an inference response
{
"usage": {
"prompt_tokens": 120,
"completion_tokens": 30,
"total_tokens": 150,
"cost": 0.000123
}
}usage.cost
Successful Chat Completions, Responses, and Messages requests return the final request cost in USD as the numeric usage.cost field.
In a regular JSON response the field is inside usage; in a streaming response it arrives in the final usage event for that API.
This is the final CloseRouter debit after billing completes, not an estimate or an internal provider price.
Retrieve a request by request ID
Read the request ID from the x-closerouter-request-id response header and substitute it in the URL. Do not use the top-level id from the response body for this lookup.
export REQUEST_ID="00000000-0000-0000-0000-000000000000"
curl https://api.closerouter.dev/v1/requests/$REQUEST_ID \
-H "Authorization: Bearer $CLOSEROUTER_API_KEY"Lookup response
{
"data": {
"request_id": "00000000-0000-0000-0000-000000000000",
"external_user": null,
"status": "completed",
"model": "openai/gpt-5.4-mini",
"api_type": "chat",
"provider": "Provider 7",
"api_key_id": "11111111-1111-4111-8111-111111111111",
"streaming": false,
"latency_ms": 934,
"usage": {
"prompt_tokens": 120,
"completion_tokens": 30,
"total_tokens": 150,
"cache_creation_tokens": 0,
"cache_read_tokens": 0,
"cost": 0.000123
},
"created_at": "2026-08-21T10:00:00.000Z",
"completed_at": "2026-08-21T10:00:01.000Z"
}
}GET /requests/{request_id}
The endpoint returns status, model, api_type, token and cache-token counts, usage.cost, and timestamps for one request.
Any active API key on the account can retrieve a request created by another key on the same account.
A request still processing has usage set to null. Terminal requests have status completed, partial, or failed; partial can include the cost of data already delivered.
Access and breakdowns
A foreign, missing, or malformed request ID returns 404.
List recent requests
Returns the account's requests newest first. limit is 1 through 100 (default 20) and pages with offset; has_more reports whether another page exists. Filter with start_date, end_date, model, status and user.
curl -G https://api.closerouter.dev/v1/requests \
-H "Authorization: Bearer $CLOSEROUTER_API_KEY" \
--data-urlencode "limit=20" \
--data-urlencode "status=failed"Period statistics
Without dates the last 30 days are used, and a period may not span more than 366 days. Repeat group_by to compute only the breakdowns you need.
curl -G https://api.closerouter.dev/v1/usage \
-H "Authorization: Bearer $CLOSEROUTER_API_KEY" \
--data-urlencode "start_date=2026-08-01" \
--data-urlencode "end_date=2026-08-31" \
--data-urlencode "group_by=day" \
--data-urlencode "group_by=model"Statistics response
GET /usage
totals and every breakdown row carry requests, failed_requests, prompt_tokens, completion_tokens, cache_creation_tokens, cache_read_tokens, total_tokens and settled cost.
group_by accepts day, model, provider, api_key, api_type and status. Omitting it returns every breakdown; unselected ones come back as empty arrays.
start_date, end_date, model (repeatable), api_key_id and timezone narrow the period.
Access and breakdowns
Breakdowns are ordered by cost, except by_day, which is chronological.
Statistics cover all account spend, including dashboard and Telegram usage, so they reconcile with the dashboard usage page.
Providers use the same public display name inference responses return in provider.
Credits
curl https://api.closerouter.dev/v1/credits \
-H "Authorization: Bearer $CLOSEROUTER_API_KEY"Response
total_credits: current available balance.
total_usage: total API usage cost.
The API returns 402 insufficient_balance when the balance is too low.
Access and breakdowns
An explicitly free request records normal zero-cost usage and creates no balance debit.