Usage

Set up

TypeScript

npm install @limitry/sdk

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

const limitry = createClient(); // reads LIMITRY_API_KEY

Python

pip install limitry

from limitry import Limitry

limitry = Limitry()  # reads LIMITRY_API_KEY

CLI

npm install -g @limitry/cli
limitry login

curl

export LIMITRY_API_KEY="lim_test_…"

Get where a subject stands

GET /v1/usage/standing

Every enabled limit on one subject — and on its shared subjects (shared, comma-separated kind:id, such as team:team_42) — with what is used, what is left and when it resets, exact as of now.

TypeScript

await limitry.usage.standing({
  kind: "user",
  id: "usr_123",
});

Python

limitry.usage.standing(kind="user", id="usr_123")

CLI

limitry usage standing --kind user --id usr_123

curl

curl -X GET "https://api.limitry.com/v1/usage/standing?kind=user&id=usr_123" \
  -H "Authorization: Bearer $LIMITRY_API_KEY"

Field	Description
kindstring, query, required	The subject's kind, as your checks send it.
idstring, query, required	The subject's id, as your checks send it.
sharedstring, query	Shared subjects to include, comma-separated kind:id (up to 4).

More about this endpoint

For showing an end user where they stand: call it from your server with your key, never from a browser. Not a check: nothing is counted. A subject with no limit here answers an empty limits list.

List who is using a limit now

GET /v1/usage/subjects

A limit’s subjects in its CURRENT window, most used first: units used, what is left, how many checks were denied — over when any were.

TypeScript

await limitry.usage.subjects({
  limitId: "lim_3f0c…",
});

Python

limitry.usage.subjects(limit_id="lim_3f0c…")

CLI

limitry usage subjects --limit-id 'lim_3f0c…'

curl

curl -X GET "https://api.limitry.com/v1/usage/subjects?limitId=lim_3f0c%E2%80%A6" \
  -H "Authorization: Bearer $LIMITRY_API_KEY"

Field	Description
limitIdstring, query, required	The limit.
limitnumber, query	How many subjects, most used first: 1–200. Default 50.

More about this endpoint

Up to about a minute behind live checks.

Get a limit’s usage over time

GET /v1/usage

Units used, checks allowed and denied for one limit — across all subjects, or one (subjectKind + subjectId) — per hour or per day (UTC), every bucket in the range included.

TypeScript

await limitry.usage.query({
  limitId: "lim_3f0c…",
});

Python

limitry.usage.query(limit_id="lim_3f0c…")

CLI

limitry usage query --limit-id 'lim_3f0c…'

curl

curl -X GET "https://api.limitry.com/v1/usage?limitId=lim_3f0c%E2%80%A6" \
  -H "Authorization: Bearer $LIMITRY_API_KEY"

Field	Description
limitIdstring, query, required	The limit.
subjectKindstring, query	With subjectId: one subject's usage, not every subject's.
subjectIdstring, query	With subjectKind: one subject's usage.
fromstring, query	Start of the range (ISO 8601). Default: 30 days before to.
tostring, query	End of the range (ISO 8601). Default: now.
granularitystring, query	One bucket per hour or per day (UTC). Default: day.

More about this endpoint

Up to about a minute behind live checks. Default: the last 30 days, by day.