Usage, quotas and rate-limit semantics

GET /v1/account/usage

Reads your account’s current request-unit usage for the active billing period.

This endpoint is Session-authenticated only — an API-key holder cannot call it directly over REST. If your integration uses an API key (not a human session), read usage programmatically via the get_usage MCP tool → instead, which is API-key-authenticated and returns the byte-identical response shape.

Auth

Authorization: Session <token> — required.

Missing/invalid/expired session → 401 unauthorized:

{ "code": "unauthorized", "message": "Authentication required.", "request_id": "..." }

Success — 200

curl https://your-getratesapi-host/v1/account/usage \
  -H "Authorization: Session gra_sess_0000000000000000000000000000000000000000000"

const res = await fetch("https://your-getratesapi-host/v1/account/usage", {
  headers: {
    Authorization: "Session gra_sess_0000000000000000000000000000000000000000000",
  },
});
const usage = await res.json();

{
  "plan": "free",
  "billing_period": { "start": "2026-10-01T00:00:00Z", "end": "2026-11-01T00:00:00Z" },
  "usage": {
    "used_units": 123,
    "quota_units": 500,
    "remaining_units": 377,
    "utilization": 0.246
  }
}

utilization is a pre-rounded ratio (4 decimal places) computed server-side — never recompute it client-side.

The response always sends Cache-Control: no-store.

Failure

503 temporarily_unavailable on entitlement/storage failure.

Request-unit quota vs. auth rate limiting — two different 429 causes

There are two unrelated mechanisms that can return HTTP 429. Always distinguish them by code, never by status code alone:

The auth-abuse rate limiter has nothing to do with your request-unit quota — hitting one never affects the other.