Checks

A check is the question your code asks before doing something that costs: may this subject do this action, at this cost? Limitry looks at every enabled limit that matches, and answers.

curl -X POST https://api.limitry.com/v1/checks \
  -H "Authorization: Bearer $LIMITRY_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
}

cost defaults to 1.

Reading the answer

Every decision is HTTP 200, allowed or not, so branch on allowed. An error status means the request itself failed: a bad key, an invalid body, or calling too fast.

remaining lists every limit that applied, so you can show “3 left today” without another call. When the answer is no, reason says which limit refused and retryAfterSeconds says when to try again. It’s null when waiting won’t help, such as an empty balance.

Several limits and shared pools

When several limits match, the check is allowed only if the cost fits all of them, and then it counts against all of them.

To draw from a shared pool as well, name up to 4 more subjects:

{
  "subject": { "kind": "user", "id": "usr_7" },
  "shared": [{ "kind": "team", "id": "t_42" }],
  "action": "ai-call"
}

Every limit on every subject must fit. Limitry charges all of them, or none. See Pools, balances and budgets.

Modes

mode	What it does
consume	The default. Decides and counts.
preview	Decides without counting: “would this be allowed?”
reserve	Decides and holds the cost until you settle it. See Reservations.

Good to know

• Retries are safe with an Idempotency-Key header: for 24 hours the same key gets the same answer and counts nothing again.
• If Limitry can’t be reached, follow each limit’s failMode. See How Limitry works.
• The key needs the checks:write scope.
• Limit changes reach checks within a minute.
• Allowed checks count toward your plan. Denied ones don’t.

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