Usage
Usage endpoints return spend data tracked by the platform.
Check usage with your API key
Section titled “Check usage with your API key”GET /v1/usageReturns plan info and key metadata for the authenticated key. Authenticate with your consumption key (sk-...) — no dashboard session required.
Authentication
Section titled “Authentication”Authorization: Bearer sk-xxxxxxxxxxxxxxxxExample
Section titled “Example”curl https://api.cheapestinference.com/v1/usage \ -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx"Response
Section titled “Response”{ "plan": { "slug": "frontier", "status": "active", "expires_at": "2026-02-15T10:00:00.000Z" }, "key": { "name": "prod-key", "type": "subscription", "created_at": "2026-01-15T10:00:00.000Z" }}| Field | Description |
|---|---|
plan.slug | Pool slug (e.g. "frontier") |
plan.status | Subscription status ("active", "expired") |
plan.expires_at | Subscription expiration timestamp |
key.name | Key label |
key.type | Key type ("subscription", or "combined" for a combined key) |
key.created_at | Key creation timestamp |
Combined keys
Section titled “Combined keys”A combined key groups several subscriptions, so its response adds a members array with one entry per subscription. plan.slug is the pool when every member is in the same pool (otherwise "combined"), plan.status is "active" while at least one member is active, and plan.expires_at is the latest expiration among the active members.
{ "plan": { "slug": "core", "status": "active", "expires_at": "2026-11-10T23:53:02.000Z" }, "key": { "name": "Combined key", "type": "combined", "created_at": "2026-10-11T00:36:05.996Z" }, "members": [ { "pool": "core", "status": "active", "hours": [8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23], "expires_at": "2026-11-10T23:53:02.000Z" }, { "pool": "core", "status": "active", "hours": [0, 1, 2, 3, 4, 5, 6, 7], "expires_at": "2026-11-10T23:53:02.000Z" } ]}Error responses
Section titled “Error responses”| Status | Reason |
|---|---|
| 401 | Missing, invalid, or unrecognized API key |
| 403 | Key is deactivated |
| 404 | Key not found in the system |
| 429 | Rate limit exceeded |
| 502 | Usage data temporarily unavailable |
Management endpoints
Section titled “Management endpoints”The following endpoints use dashboard authentication (session token or management key mk_).
List all keys
Section titled “List all keys”GET /api/usageReturns all your keys with usage stats across 4 time periods and subscription info. Rate limited to 12 requests per 12 hours.
Example
Section titled “Example”curl https://api.cheapestinference.com/api/usage \ -H "Authorization: Bearer mk_your_management_key"Response
Section titled “Response”{ "success": true, "data": [ { "id": "key-uuid", "name": "user-alice", "type": "subscription", "plan": "frontier", "isActive": true, "usage": { "last1h": { "requests": 3, "tokens": 8200, "promptTokens": 7800, "completionTokens": 400 }, "last24h": { "requests": 45, "tokens": 128000, "promptTokens": 120000, "completionTokens": 8000 }, "last7d": { "requests": 312, "tokens": 890000, "promptTokens": 840000, "completionTokens": 50000 }, "last30d": { "requests": 1287, "tokens": 35895828, "promptTokens": 35634452, "completionTokens": 261376 } }, "subscription": { "status": "active", "expiresAt": "2026-04-23T15:12:31.565Z" }, "createdAt": "2026-03-05T13:29:01.800Z" } ]}| Field | Description |
|---|---|
id | Key UUID |
name | Key label |
type | Key type ("subscription") |
plan | Pool slug (e.g. "frontier") |
isActive | Whether the key is currently active |
usage | Request and token counts across 4 periods: last1h, last24h, last7d, last30d |
subscription | Present for subscription keys — status and expiry |
createdAt | Key creation timestamp |
This endpoint is rate limited to 12 requests per 12 hours. Cache the response client-side.
Get single key
Section titled “Get single key”GET /api/usage/:keyIdReturns info for a specific key (by UUID).
Example
Section titled “Example”curl https://api.cheapestinference.com/api/usage/KEY_UUID \ -H "Authorization: Bearer mk_your_management_key"Returns the same shape as a single item from the list above.