Usage

Usage endpoints return spend data tracked by the platform.

Check usage with your API key

GET /v1/usage

Returns budget, rate limits, plan info, credit balance, and key metadata for the authenticated key. Authenticate with your consumption key (sk_xxx) — no dashboard session required.

Authentication

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx

Example

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

Response

{
  "budget": {
    "spent": 1.23,
    "limit": 10.0,
    "duration": "30d",
    "resets_at": "2026-02-15T10:00:00.000Z"
  },
  "rate_limits": {
    "rpm": 60,
    "tpm": 3333
  },
  "plan": {
    "slug": "standard",
    "status": "active",
    "expires_at": "2026-02-15T10:00:00.000Z"
  },
  "credits": {
    "balance": 5.0
  },
  "key": {
    "name": "prod-key",
    "type": "subscription",
    "created_at": "2026-01-15T10:00:00.000Z"
  }
}

Field	Description
budget.spent	Total spend in USD for the current budget period
budget.limit	Budget cap (null if unlimited)
budget.duration	Budget reset interval (e.g. "30d")
budget.resets_at	Next budget reset timestamp
rate_limits.rpm	Requests per minute limit
rate_limits.tpm	Tokens per minute limit
plan.slug	Plan tier ("standard", "pro", or null for credit keys)
plan.status	Subscription status ("active", "expired")
plan.expires_at	Subscription expiration timestamp
credits.balance	Account credit balance in USD
key.name	Key label
key.type	"subscription" or "credit"
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": "pro",
      "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	"subscription" or "credit"
plan	Plan tier ("standard", "pro", or "credits")
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.

---

Plans (public)

GET /api/plans

Returns all available plans with rate limits and pricing. No authentication required.

Example

curl https://api.cheapestinference.com/api/plans

Response

[
  {
    "slug": "standard",
    "name": "Standard",
    "priceUsdc": "20",
    "rateLimits": {
      "tpm_limit": 3333,
      "rpm_limit": 60
    }
  },
  {
    "slug": "pro",
    "name": "Pro",
    "priceUsdc": "60",
    "rateLimits": {
      "tpm_limit": 13333,
      "rpm_limit": 200
    }
  }
]