Rate limits

What counts

• Only tools/call consumes allowance. Protocol traffic, initialize, tools/list, notifications, is never counted or blocked.
• Only successfully executed tool calls count. A failed call, whether validation, auth, or a server fault, is free, so retry loops and pre-flight checks cost nothing.
• One call is one call. No tool is weighted, and no tool is gated behind a plan: all 315 are on every plan.
• The 3 meta-tools are metered like any other. set_birth_profile, get_reading_protocol and get_tool_catalog each cost one call when they succeed.

Budget per reading, not per request

A reading is not one call. The mandatory floors are 20 calls for a life-area question, 12 for a focused one, and 5 for a factual lookup, with full readings typically spending 25 to 40. So 300 calls a month is roughly seven to twelve full readings. Size your budget on readings and read reading depth and call floors for the arithmetic.

Scope: one allowance per account

Every API key created from a Lumin account, and that account's own OAuth sign in (the Claude connector), draw on one monthly allowance. Three keys and a connector are four ways into one meter, and revoking a key does not reset it. One account used from three clients is still one meter.

Refresh

The monthly allowance refreshes on the 1st of each month at 00:00 UTC. Extra calls on the account (bought through a top up, or given by Lumin) sit outside the refresh cycle: they never expire and are drawn down only after the monthly allowance is spent.

Headers

Any request that gets past authentication carries the current meter state, so you can watch your budget without a separate endpoint. A 401 (no credentials, or credentials rejected) returns before this middleware runs, so it carries none of these:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 187

A 429 additionally carries Retry-After in seconds. Note that it points at the monthly refresh, so it can be days, not seconds. Sleeping on it is almost never the right move.

A call drawn from the account's extra calls, because the free allowance alone could not cover it, carries one more header, X-CallPack-Balance, the extra calls left after the draw (the header keeps its older name). It is not sent on a call the free allowance covered outright.

The 429 shape

When both the free allowance and the extra calls are used up, tools/call requests return HTTP 429 with a JSON-RPC error object, code -32000:

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32000,
    "message": "Monthly call allowance reached (300 tool calls this month) and no call pack balance remains on this account. The allowance refreshes on the 1st of the month, UTC. Call packs: https://lumin.guru/pricing",
    "data": {
      "retryAfterSeconds": 604800,
      "limit": 300,
      "remaining": 0,
      "packBalance": 0,
      "resetAt": "2026-08-01T00:00:00.000Z"
    }
  }
}

resetAt is the ISO timestamp of the 1st of next month, UTC. retryAfterSeconds matches the Retry-After header. packBalance is the extra calls balance at the moment of the 429 (the field keeps its older name), and a 429 only happens when that is exhausted, so it always reads 0 here. The right handling is to surface the situation to your user or point them at a top up, not to queue a retry.

More volume

For a bigger integration, write to contact@lumin.guru. There is no allowance per key. Extra capacity is extra calls on your account, bought through a top up or given by Lumin, and every key on the account and its Claude connector draw on them once the free allowance is spent. Your client code does not change: same headers, same 429 shape.