Get Usage by Model

GET /api/open/v1/usage/models

Request parameters

Parameter	In	Type	Required	Default	Description
start_timestamp	query	integer	No	See below	Start time (inclusive), unix seconds
end_timestamp	query	integer	No	See below	End time (inclusive), unix seconds
limit	query	integer	No	10	Number of models to return, from 1 to 100; values outside this range return 400

Time range rules:

• Both omitted: the last 30 days.
• Only start_timestamp: 30 days forward, capped at the current time.
• Only end_timestamp: 30 days backward.
• The range can be at most 366 days.

Request example

curl "https://www.routeapi.ai/api/open/v1/usage/models?start_timestamp=1726400000&end_timestamp=1729000000&limit=10" \
  -H "Authorization: Bearer $ROUTEAPI_MANAGEMENT_KEY"

Response example

{
  "success": true,
  "message": "",
  "data": {
    "items": [
      {
        "model_name": "gpt-4o",
        "prompt_tokens": 120000,
        "completion_tokens": 30000,
        "total_tokens": 150000,
        "amount": 3.20
      }
    ],
    "start_timestamp": 1726400000,
    "end_timestamp": 1729000000
  }
}

Response fields

Field	Type	Description
items[].model_name	string	Model name
items[].prompt_tokens	integer	Total input tokens for the model in the range
items[].completion_tokens	integer	Total output tokens for the model in the range
items[].total_tokens	integer	Input plus output tokens
items[].amount	number	Amount consumed by the model in the site currency, two decimals
start_timestamp	integer	Effective start time
end_timestamp	integer	Effective end time

Errors

HTTP	code	Scenario
400	invalid_request	limit is not an integer between 1 and 100, a timestamp is negative, or the time range is invalid
429	—	Per-user query rate limit exceeded (default 30/minute); the body may be empty

For other common error codes, see Platform API errors.

Notes

• Results are sorted by total_tokens descending; ties are ordered by model name ascending, so the order is stable.
• Only consumption (billing) logs are counted; failed requests are excluded.
• Token counts are raw counts, not millions.
• Amounts use the site display currency; see Get balance.
• Each row’s amount is rounded independently, so the sum of rows may differ from a total by up to 0.01.
• This endpoint shares the per-user query rate limit (default 30/minute) with Usage, Account logs, Export logs, and Usage by Key. See Rate limits.