Checks

Set up

npm install @limitry/sdk

import { createClient } from "@limitry/sdk";

const limitry = createClient(); // reads LIMITRY_API_KEY

pip install limitry

from limitry import Limitry

limitry = Limitry()  # reads LIMITRY_API_KEY

npm install -g @limitry/cli
limitry login

export LIMITRY_API_KEY="lim_test_…"

Check whether a subject may act

POST /v1/checks

Asks whether subject may do action at cost, given every enabled limit that applies, and — in consume mode — uses it.

await limitry.checks.create({
  subject: {
    kind: "user",
    id: "usr_123",
  },
  action: "ai-call",
});

limitry.checks.create(
    subject={"kind": "user", "id": "usr_123"},
    action="ai-call",
)

limitry check <kind>:<id> <action>, short for:

limitry checks create \
  --subject '{"kind":"user","id":"usr_123"}' \
  --action ai-call

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":"usr_123"},"action":"ai-call"}'

Field	Description
`subject`object, required	Who is acting, as `{"kind": "user", "id": "usr_123"}`.
`shared`array	Shared subjects it also draws from — a team's, org's or project's pool (at most 4). Every limit on every subject must fit; all are charged, or none.
`action`string, required	What the subject wants to do.
`cost`number	Units it would use. Default 1.
`mode`string	`consume` (default) decides and uses; `preview` decides without using; `reserve` decides and HOLDS `cost` (an estimate) until you commit the actual amount or release it — see `reservation` in the answer. Only a reservation takes a slot of a `concurrent` limit.
`ttlSeconds`number	With `reserve`: how long the hold lasts before it releases itself. Default 300, at most 3600.

More about this endpoint

Always 200 for a decision: read allowed; remaining shows what is left per limit and retryAfterSeconds when to try again. An Idempotency-Key header makes a retried check return the same decision without using twice. Its API-key check is cached briefly for speed: a revoked key can keep working here for up to 60 seconds.