Usage API | EvaEsi Dev

Endpoints

Route	Purpose
`GET /api/v1/usage`	Current billing-period totals and allowance state
`GET /api/v1/usage/history`	Historical billing periods, newest first
`GET /api/v1/limits`	Current request, rung, and monthly allowance envelope

Scope Rules

These endpoints require the same bearer authentication as the rest of the public API, including the inference scope: a key without it receives 403 INSUFFICIENT_SCOPE even on these read-only routes. If your key is bound to a developer project, usage is project-scoped. If the key has no project binding, the API falls back to user-level totals.

Current usage

{
  "period_start": "2026-04-01T00:00:00Z",
  "period_end": "2026-05-01T00:00:00Z",
  "input_rungs": 48100,
  "output_rungs": 80300,
  "total_rungs": 128400,
  "request_count": 93,
  "allowance": 10000000,
  "remaining": 9871600,
  "estimated_cost_pence": 0
}

Rung totals here are billing rungs, not raw byte counts: instant and elements meter 1 rung per byte, while reasoning traffic is recorded at 1.4× (rungs × 7 / 5, integer division), the multiplier is already included in these totals.

allowance: 0 is reserved to mean unlimited (with remaining: null), but no live tier uses it, Developer is 10,000,000 rungs/month and Premium is 20,000,000, so remaining is always a number in practice. The current implementation returns 0 for estimated_cost_pence rather than exposing metered overage calculations.

Both endpoints emit period bounds in the same RFC3339 shape with a literal Z suffix (2026-04-01T00:00:00Z).

Usage History

{
  "periods": [
    {
      "period_start": "2026-04-01T00:00:00Z",
      "period_end": "2026-05-01T00:00:00Z",
      "input_rungs": 48100,
      "output_rungs": 80300,
      "total_rungs": 128400,
      "request_count": 93
    }
  ]
}

History is returned in descending period order and is currently capped to the most recent 12 periods.

Limits

{
  "tier": "developer",
  "requests_per_minute": 300,
  "rungs_per_minute": 5000000,
  "monthly_allowance": 10000000,
  "monthly_used": 128400
}

Developer keys currently map to the Growth rate envelope and Premium keys map to the Scale envelope. See /docs/billing/rate-limits for the operational behavior of headers and throttling responses.

requests_per_minute and rungs_per_minute in this response are the nominal tier constants. The enforced per-minute ceiling may be overridden per tier by platform configuration, treat the x-ratelimit-limit header on live responses as authoritative and this endpoint as the tier baseline.

Each key also carries a per-day rung ceiling of rungs_per_minute × 1440 (7,200,000,000/day on Developer), charged against the estimated cost of each request, prompt bytes plus max_output_rungs (or the model's default output limit when omitted), not actual output. Oversized max_output_rungs values consume this budget even when the model returns far less. Breaching it returns 429 RATE_LIMITED, the same code as the per-minute limit.

Errors

401 INVALID_API_KEY or 401 MISSING_API_KEY for auth failures
403 INSUFFICIENT_TIER when bearer API access is not allowed for the subscription tier
403 INSUFFICIENT_SCOPE when the key lacks the inference scope, required even for these read-only routes
429 RATE_LIMITED: usage reads consume the same per-minute request budget as inference; avoid tight polling loops
500 DB_ERROR when usage data could not be queried
503 DB_UNAVAILABLE when the database is not available

Start from a live reference page.