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 (subject, as kind:id, such as user:usr_123) — 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({
  subject: "user:usr_123",
});

Python

limitry.usage.standing(subject="user:usr_123")

CLI

limitry usage standing --subject user:usr_123

curl

curl -X GET "https://api.limitry.com/v1/usage/standing?subject=user%3Ausr_123" \
  -H "Authorization: Bearer $LIMITRY_API_KEY"

Field	Description
subjectstring, query, required	The subject, as kind:id: its kind and id as your checks send them.
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, and how many checks it refused.

TypeScript

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

Python

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

CLI

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

curl

curl -X GET "https://api.limitry.com/v1/usage/subjects?limitId=lmt_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 refused for one limit — across all subjects, or one (subject, as kind:id) — per hour or per day (UTC), every bucket in the range included.

TypeScript

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

Python

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

CLI

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

curl

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

Field	Description
limitIdstring, query, required	The limit.
subjectstring, query	One subject's usage, not every subject's, as kind:id.
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.