Skip to content
Limitry Docs

Checks

A check is the question your product asks Limitry before doing something that costs: may this subject do this action, at this cost? Limitry evaluates every enabled limit that applies and answers in milliseconds, from Cloudflare’s edge.

Terminal window
curl -X POST https://api.limitry.com/v1/checks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c…" \
  -d '{"subject":{"kind":"user","id":"usr_123"},"action":"generate-image","cost":1}'
{
  "id": "chk_9d2e…",
  "allowed": false,
  "reason": { "code": "limit_exceeded", "limit": "lim_3f0c…" },
  "remaining": [
    {
      "limit": "lim_3f0c…",
      "name": "Daily images",
      "unit": "images",
      "window": "day",
      "remaining": 0,
      "resetsAt": "2026-10-05T00:00:00.000Z"
    }
  ],
  "retryAfterSeconds": 41200
}
  • A “no” is an answer, not an error. Every decision is HTTP 200 — branch on allowed. Error statuses mean the request itself failed (a bad key, an invalid body, or calling Limitry too fast).
  • All or none. When several limits apply, the check is allowed only if the cost fits every one of them, and then uses all of them.
  • Shared pools. Add "shared": [{ "kind": "team", "id": "t_42" }] (up to 4) and the check also draws from those subjects’ limits — a team’s, org’s or project’s pool. Every limit on every subject must fit; all are charged, or none, and a pool is never overspent however many users draw from it at once.
  • mode: consume (the default) decides and uses; preview only decides — “would this be allowed?”; reserve decides and holds an estimate you settle later — see Reservations.
  • Retries are safe with an Idempotency-Key header: the same key returns the same decision for 24 hours and uses nothing again.
  • remaining lists every limit that applied, so your app can show “3 left today” without another call.
  • When Limitry can’t be reached, follow each limit’s failMode: open (the default) allows, closed denies — so an outage of Limitry need not become an outage of your product.

The key needs the checks:write scope. Limit changes reach checks within a minute. A revoked key can keep working here for up to 60 seconds (its check is cached for speed). Checks count toward your plan (100,000 per month on the free plan; see Settings → Billing).

The same operation is limitry checks create on the command line and a tool on the MCP server.