Check usage

Usage of your key or team member by model and date, from /v1/usage or the OpenAI legacy usage endpoint.

Usage of your API key, or of every key of its team member, by model and date. GET /v1/dashboard/billing/usage returns the key's all-time usage in the OpenAI legacy format.

Method and path

GET/v1/usage

GET/v1/dashboard/billing/usage

Base URL https://api.relayvia.dev/v1. Send the key as Authorization: Bearer sk-....

Common parameters

Parameter	Type	Required	Description
start	integer \| string	No	Start time, Unix seconds or RFC 3339. Default: 24 hours before `end`. Rounded down to the hour.
end	integer \| string	No	End time (exclusive), Unix seconds or RFC 3339. Default: now. Rounded up to the hour; at most 31 days after `start`.
model	string	No	Comma-separated model names, up to 50; exact match, case-insensitive.
group_by	string	No	`none` (default), `model`, `date` or `model,date`.
tz	string	No	IANA time zone for `date` grouping and the times in the response. Default `UTC`.
scope	string	No	`key` (default) for this key, or `member` for every key of the team member who owns it.

Differences from the original API

Numbers come from hourly totals, so approximate is always true and done_through says up to when the totals are complete; usage after that is not counted yet, which is not the same as zero. For exact charges, use the ledger on the console's Billing page.
Read-only and free, with the same limit of 60 requests per minute per key as /v1/balance. Invalid parameters return 400 invalid_request with param naming the field; a range longer than 31 days is reported on start.
The legacy endpoint returns total_usage in US cents for the key's whole lifetime and ignores start_date and end_date.

Request examples

cURL

curl "https://api.relayvia.dev/v1/usage?group_by=model&tz=Asia/Taipei" \
  -H "Authorization: Bearer sk-..."

Python

import requests

resp = requests.get("https://api.relayvia.dev/v1/usage", headers={"Authorization": "Bearer sk-..."}, params={"group_by": "model", "tz": "Asia/Taipei"})
print(resp.json())

JavaScript

const resp = await fetch("https://api.relayvia.dev/v1/usage?group_by=model&tz=Asia/Taipei", {
  headers: { Authorization: "Bearer sk-..." },
});
console.log(await resp.json());

Response examples

Field	Type	Description
total	object	Totals over the whole range.
items	array	One row per `group_by` value, with `model` and `date` (`YYYY-MM-DD` in `tz`) as grouped, sorted by `amount_usd` from high to low. Empty when `group_by` is `none`.
amount_usd	number	Amount charged, in US dollars. Failed requests are free.
requests	integer	Successful requests.
failed_requests	integer	Failed requests, not charged.
done_through	string	The time up to which the totals are complete.

Response

{
  "object": "usage",
  "scope": "key",
  "start": "2026-11-03T00:00:00+08:00",
  "end": "2026-11-04T00:00:00+08:00",
  "tz": "Asia/Taipei",
  "group_by": "model",
  "approximate": true,
  "done_through": "2026-11-03T23:00:00+08:00",
  "total": {
    "amount_usd": 3.12,
    "requests": 120,
    "failed_requests": 0,
    "prompt_tokens": 216000,
    "completion_tokens": 50400,
    "cache_read_tokens": 108000,
    "cache_write_tokens": 0,
    "reasoning_tokens": 0
  },
  "items": [
    {
      "model": "claude-opus-5",
      "amount_usd": 2.4,
      "requests": 80,
      "failed_requests": 0,
      "prompt_tokens": 144000,
      "completion_tokens": 33600,
      "cache_read_tokens": 72000,
      "cache_write_tokens": 0,
      "reasoning_tokens": 0
    },
    {
      "model": "gpt-5.5",
      "amount_usd": 0.72,
      "requests": 40,
      "failed_requests": 0,
      "prompt_tokens": 72000,
      "completion_tokens": 16800,
      "cache_read_tokens": 36000,
      "cache_write_tokens": 0,
      "reasoning_tokens": 0
    }
  ]
}

OpenAI legacy format

{
  "object": "list",
  "total_usage": 3120
}

Errors this endpoint returns

HTTP	code	When
400	invalid_request	A parameter is invalid. If the model rejected it, the message is this sentence, or `Invalid value for parameter <param>.` with `param` set.
401	invalid_api_key	The API key does not exist, is disabled or has expired.
403	forbidden	The key may not use this model, the source IP is not on the allowlist, or the account is disabled.
429	rate_limited	Too many requests: per IP, per key, per account, or too many requests in progress at once.

Every code, its fixed message and what to do are on the error codes page.