Usage

Usage endpoints return spend data tracked by the platform.

Check usage with your API key

GET /v1/usage

Returns plan info and key metadata for the authenticated key. Authenticate with your consumption key (sk-...) — no dashboard session required.

Authentication

Authorization: Bearer sk-xxxxxxxxxxxxxxxx

Example

curl https://api.cheapestinference.com/v1/usage \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx"

Response

{
  "budget": null,
  "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
budget	null for Unlimited subscription keys
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")
key.created_at	Key creation timestamp

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

The following endpoints use dashboard authentication (session token or management key mk_).

List all keys

GET /api/usage

Returns all your keys with usage stats across 4 time periods and subscription info. Rate limited to 12 requests per 12 hours.

Example

curl https://api.cheapestinference.com/api/usage \
  -H "Authorization: Bearer mk_your_management_key"

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

GET /api/usage/:keyId

Returns info for a specific key (by UUID).

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.