Usage & Quota

Usage time-series

Two read endpoints expose your organization's API usage, aggregated from request logs into daily UTC buckets.

The same data is available to the developer portal (session-authenticated) at /api/developer/usage and /api/developer/usage/keys/{apiKeyId} under the developers:read permission.

Query parameters

Response

{
  "data": {
    "period": "30d",
    "apiKeyId": null,
    "series": [
      {
        "date": "2026-05-16",
        "requests": 1280,
        "errors": 14,
        "errorRatePct": 1.09,
        "p95LatencyMs": 142,
        "rateLimitHits": 0
      }
      // … one object per UTC day in the window
    ],
    "totals": {
      "requests": 38400,
      "errors": 410,
      "errorRatePct": 1.07,
      "p95LatencyMs": 151,
      "rateLimitHits": 3
    },
    "generatedAt": "2026-06-14T00:00:00.000Z"
  },
  "meta": { ... }
}

Field semantics

• Buckets are calendar days in UTC (date_trunc('day', created_at AT TIME ZONE 'UTC')). The series is 0-padded — every day in the window appears exactly once, even with zero traffic, so the array length is deterministic.
• requests — total requests in the bucket.
• errors — responses with status >= 400. errorRatePct is errors / requests * 100 (0 when there were no requests).
• p95LatencyMs — 95th-percentile latency for the bucket, or null when the bucket has no rows. The window totals.p95LatencyMs is recomputed over the whole window (it is not the average of the per-day percentiles).
• rateLimitHits — requests rejected with 429 (rate-limited).
• apiKeyId — null on the org summary; the key id on the per-key breakdown.

The key breakdown only returns data for an API key your organization owns; an unknown or non-owned key id returns 404.

Monthly quota

Your organization may have a monthly API request ceiling (a per-calendar-month cap, configured by the platform operator). Quota is a coarse protection ceiling, not a billing meter — a small amount of under-counting is possible by design.

• If your organization has no configured quota, requests are unlimited.
• When you exceed the ceiling, the platform responds in one of two modes (operator-controlled):
  • Warning mode (default): the request still succeeds, but responses carry an X-Quota-Warning: true header. Treat this as a signal to reduce volume or request a higher ceiling.
  • Enforce mode: requests over the ceiling are rejected with 429 Too Many Requests and the error code: "org_quota_exceeded".

The org quota is checked before the per-key rate-limit tier, so an org-ceiling rejection is distinguishable from a per-key tier rejection (code: "rate_limit_exceeded").