Reservations

Some work only knows its cost afterwards — an AI call billed by tokens, a job billed by minutes. A reservation holds an estimate while the work runs, then settles at the actual amount.

1. Reserve

Check with mode: "reserve" and your estimate as the cost:

curl -X POST https://api.limitry.com/v1/checks \
  -H "Authorization: Bearer $LIMITRY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "subject": { "kind": "user", "id": "u_42" }, "action": "ai-call",
        "cost": 2000, "mode": "reserve" }'

It decides exactly like a normal check. When allowed, the estimate is held — every other check for that subject sees it as used — and the answer carries the reservation:

{
  "allowed": true,
  "remaining": [{ "limit": "lim_…", "remaining": 8000, "…": "…" }],
  "reservation": { "id": "rsv_…", "expiresAt": "2026-10-04T12:05:00Z" }
}

A “no” holds nothing and has no reservation.

2. Settle

When the work is done, commit what it actually used:

curl -X POST https://api.limitry.com/v1/reservations/rsv_…/commit \
  -H "Authorization: Bearer $LIMITRY_API_KEY" \
  -H "Content-Type: application/json" -d '{ "cost": 1310 }'

Less than you held comes back at once. More is charged in full — the work happened — even past the limit, so the next check sees the true total.

If the work did not happen, release it: POST /v1/reservations/{id}/release gives the whole hold back.

Settling is safe to retry: the same commit (or release) answers the same. Releasing a committed reservation, or committing a released one, is refused (400).

Expiry

A hold lasts ttlSeconds (default 300, at most 3,600 — set it on the check). One that nobody settles gives itself back when it expires, so a crashed worker never keeps a subject blocked. If your work finished after all, a late commit (within 24 hours) still charges what it used.

For longer work, extend a held reservation as a heartbeat — POST /v1/reservations/{id}/extend with { "ttlSeconds": 600 } — it then expires that long from now. A reservation can also hold a slot of a concurrent limit.

Good to know

• A subject may hold at most 1,000 open reservations; past that a reserve is a normal “no” with reason.code: "too_many_reservations".
• A reserve counts as one check on your plan; settling is free.
• Reservations need the same checks:write scope as checks.