Usage API Reference

Use these endpoints to inspect the current month for one usage kind or for both make and ai together.

Get Usage

Endpoint: GET /v1/usage

Query Parameters

Parameter	Type	Description
`kind`	string	`"make"` or `"ai"` (default: `"make"`)

Request

curl -H "Authorization: Bearer once_live_xxxxxxxxxxxxx" \
  "https://api.onceonly.tech/v1/usage?kind=ai"

Response

{
  "plan": "starter",
  "month": "2026-03",
  "usage": 128,
  "limit": 100000,
  "requests_total_month": 410,
  "blocked_total_month": 7
}

Field Meaning

plan - Current plan for the API key
month - Current UTC billing bucket in YYYY-MM
usage - Current enforcement counter for that kind
limit - Monthly plan limit for that kind
requests_total_month - Raw traffic seen this month
blocked_total_month - Requests blocked after hitting the monthly limit

Important Semantics

In the current backend, usage is not the same thing as raw traffic:

For make, requests_total_month counts all check-lock requests, while usage is the counter used for plan enforcement.
For ai, requests_total_month counts all lease/run attempts, while usage tracks acquired work that counts against the AI limit.

If you want the broadest operational view, use requests_total_month together with blocked_total_month.

Get Usage For All Kinds

Endpoint: GET /v1/usage/all

Request

curl -H "Authorization: Bearer once_live_xxxxxxxxxxxxx" \
  "https://api.onceonly.tech/v1/usage/all"

Response

{
  "plan": "starter",
  "month": "2026-03",
  "make": {
    "usage": 42,
    "limit": 20000,
    "requests_total_month": 314,
    "blocked_total_month": 3,
    "charged_total_month": 0,
    "polling_total_month": 0
  },
  "ai": {
    "usage": 128,
    "limit": 100000,
    "requests_total_month": 410,
    "blocked_total_month": 7,
    "charged_total_month": 128,
    "polling_total_month": 61
  }
}

Response Headers

GET /v1/usage/all also sets:

X-Request-Id
X-OnceOnly-Plan
X-OnceOnly-Month

Field Meaning

make.usage / ai.usage - Current enforcement counters
requests_total_month - Total requests observed for that kind this month
blocked_total_month - Requests blocked after plan limit enforcement
charged_total_month - AI requests that were newly acquired and charged
polling_total_month - AI requests that attached to already running work

charged_total_month and polling_total_month are only meaningful for the ai section.

Errors

401 - Missing Authorization

{
  "detail": "Missing Authorization Bearer token"
}

403 - Invalid or Disabled API Key

{
  "detail": "Invalid API key"
}

429 - Rate Limited

{
  "detail": {
    "error": "rate_limited"
  }
}

See also: Free Plan | AI Run API | Runs & Events API