Rate limits API

Manage the request and token limits that the Policy Engine's Rate, Token & Timeout Limits card configures, as typed resources. You never write QuilrQL: each write is validated and published as one policy revision. For what a limit counts and what clients see when they hit one, see Rate, token and budget limits.

This page covers rate limits (requests and tokens over a window). Spend budgets, budget grants and pricing are in the Budgets API: they have their own scopes (budgets:*), are priced in USD and report usage from a periodic snapshot, while rate limits count live.

Rate limits

Requests or tokens

Per user, app, model...

Raises

Temporary, per subject

Up to a ceiling

Guards

Tokens per request

Timeout, per model

Exemptions

Users, apps, groups

Until an expiry

Responses

Custom 429 message

Help link, retry hint

QuilrAI

Resource	What it is	Read scope	Write scope
Rate limits	A counter of requests, input_tokens, output_tokens or total_tokens over a rolling or calendar window, one counter per group_by combination.	limits:read	limits:write
Grants	A temporary raise of one subject's rate limit, until expires_at. Not a policy revision.	limits:read	limits:grant
Request guards	Maximum total tokens per request and a request timeout, for a scope. The strictest value wins.	limits:read	limits:write
Model limits	Per-model tokens-per-request and timeout caps, optionally for one provider label.	limits:read	limits:write
Limit exemptions	Skip some or all rate limits for users, apps, smart groups or app tags, until an expiry.	limits:read	limits:write
Limit responses	The message, help link and retry hint clients get when a limit blocks them, per app scope.	limits:read	limits:write
Usage and effective limits	Live counters of one rate limit, and every limit that applies to an app, user and model.	limits:read	-

limits:read does not need read. Try every operation in the Management API playground.

Before you start

• The Policy Engine must be on for the LLM Gateway. While it is off, every call answers 409 policy_not_enabled.
• Limits are regional. Every gateway in a region shares the same counters, so a limit of 60 requests per minute is 60 for the region, not per gateway. Usage reads report scope: "regional".
• Writes follow the same rules as routing controls: content-idempotent PUT, If-Match ETags, If-None-Match: * for create only, ?dry_run=true, console rows read only, and POST /controls/_batch for several changes in one revision. See Writes, versions and idempotency.

Rate limits

{
  "label": "Support requests per minute",
  "metric": "requests",
  "limit": 60,
  "window": {"kind": "rolling", "unit": "minute"},
  "group_by": ["user"],
  "scope": {"apps": ["support-bot"]},
  "mode": "enforce",
  "adjustments": {"ceiling": 120, "max_duration": "2d"},
  "alerts": [{"at_pct": 80}]
}

Field	Values
metric	requests, input_tokens, output_tokens, total_tokens. Spend is a budget.
window	Rolling: {"kind": "rolling", "unit": "minute" | "hour" | "day" | "week" | "month" | "year", "size": n}. Calendar: {"kind": "calendar", "unit": "day" | "week" | "month" | "year", "timezone": "Europe/Berlin"} (UTC by default). Lifetime windows are budgets.
group_by	One counter per distinct combination; [] is one shared counter.
scope	apps, smart_groups, users, app_tags. Every non-empty list must match; empty lists do not restrict.
mode	enforce (default), alert (count and alert, never block) or paused.
adjustments	Needed for grants: ceiling (highest limit a grant may set), max_duration (for example 2d, default 366d), optional auto_approve, overflow and requestable.
overrides	Rate limit ids this one replaces where both apply.

group_by accepts short aliases; responses return the full field name:

Alias	Counts per
user / user_id	user email / user id
app / app_key	app / gateway key
smart_group	the user's active smart group
model / provider / provider_label	served model / provider type / provider label
method_type	client API family (Chat Completions, Responses, ...)
tenant	the whole organization

metric, group_by and window are the counter's identity

They cannot change in place (422 identity_field_immutable), because usage is counted against them. To change one, create a rate limit with a new id and delete the old one. An id used before with another identity is 422 quota_id_reused.

POST /controls/rate-limits:migrate-legacy converts an app's older per-app window limits into rate limits in one revision; ?dry_run=true shows the result first.

Temporary raises (grants)

A grant raises one subject's limit until expires_at: extra adds to the limit, limit sets it (exactly one). Name the subject by the rate limit's grouping, for example {"user": "alex@example.com"}.

export API="$MANAGEMENT_URL/llmgateway/management/v1"
auth=(-H "Authorization: Bearer $MANAGEMENT_KEY" -H 'Content-Type: application/json')

curl -X POST "$API/controls/rate-limits/support-rpm/grants" "${auth[@]}" -H "Idempotency-Key: launch-alex" \
  -d '{"subject": {"user": "alex@example.com"}, "extra": 60, "expires_at": "2026-11-01T00:00:00Z", "reason": "launch"}'

• The rate limit needs adjustments (409 rate_limit_not_adjustable). A grant above ceiling is 422 grant_above_ceiling; longer than max_duration is 422 grant_too_long.
• A new grant for the same subject supersedes the active one (returned as superseded).
• Revoke with DELETE /controls/rate-limits/{id}/grants/{grant_id}?reason=... and the grant ETag in If-Match.
• Grants never publish a policy revision.

Usage

GET /controls/rate-limits/{id}/usage returns live counters: one subject's bucket with subject.user= or subject.app= (or bucket=), or the busiest buckets (top, default 20).

Request guards and model limits

• Request guards cap max_tokens_per_request and timeout_s for a scope. When several apply at one priority, the strictest value wins.
• Model limits set the same caps per model: {"limits": [{"model": "gpt-4.1", "max_tokens_per_request": 4000}]}, with optional provider_label per entry. For requests or tokens per window per model, use a rate limit with group_by: ["model"]; the older window keys on model limits are 422 deprecated_field.

Exemptions

{"scope": {"users": ["oncall@example.com"]}, "quotas": "all", "reason": "on call", "expires_at": "2027-01-01T00:00:00Z"} skips every rate limit for that user until the expiry. quotas can instead list rate limit ids. Exemptions here cover rate limits only; budget exemptions are in the Budgets API (422 budget_exemption_not_supported). expires_at must be in the future.

Custom limit responses

A limit response replaces the default message of a blocked request for its scope:

{"scope": {"apps": ["support-bot"]}, "message": "Limit {limit} reached; resets {reset}", "url": "https://help.example.com/limits", "retry": "never"}

message may use {limit}, {reset} and {budget}. url must be https://. retry: "never" tells clients not to retry; default keeps the normal retry hint. Two limit responses must name app lists with no app in common, otherwise 422 limit_response_conflict, so each app gets exactly one message.

Effective limits

GET /limits/effective?app=&user=&requested_model=&model=&provider_label= returns every rate limit, request guard and model limit that applies, the one that binds first (tightest, tightest_tokens_per_request), exemptions, grants and the limit response, with live counters unless include_usage=false. unknown_facts lists inputs the active policy reads that the query did not supply (for example a user id); they count as empty.

Errors

Status	Codes
400	invalid_request, invalid_cursor, invalid_resource_id, idempotency_key_required
404	rate_limit_not_found, grant_not_found
409	policy_not_enabled, rate_limit_not_adjustable, grant_not_active, rule_not_api_managed
412	version_conflict
422	validation_failed, identity_field_immutable, quota_id_reused, quota_id_conflict, kind_not_supported, grant_above_ceiling, grant_too_long, invalid_grant, invalid_subject, subject_unresolved, subject_not_in_budget, duplicate_subject, invalid_quota_adjustments, override_target_not_allowed, limit_response_conflict, budget_exemption_not_supported, exemption_expired, deprecated_field, unsupported_fields
428	precondition_required (revoking a grant needs If-Match)

Endpoints

Rate limits, usage and grants

GET/controls/rate-limits

List rate limits

Every managed rate limit with its ETag, then the console policy rules of the same kind as read-only rows (source console, policy, rule_index, view). Console rows cannot be written here (409 rule_not_api_managed). Paginated (limit, cursor bound to the revision) and filtered by source, app, requested_model, mode and references.

REQUIRESlimits:read

Path, query & header parameters 7

limit (query)integeroptional

Page size.

min: 1max: 500default: 100

cursor (query)stringoptional

next_cursor of the previous page; bound to the revision (409 collection_changed when the policy changed).

source (query)objectoptional

Only managed resources or only console rows.

"managed""console"

app (query)stringoptional

Rows that can apply to this app (rows scoped only by smart group, user or tag are kept). app_name is a deprecated alias.

requested_model (query)stringoptional

Rows that can apply to this requested model. model is a deprecated alias.

mode (query)stringoptional

Rows with this mode (routes: active, observe, disabled; limits: enforce, alert, paused).

references (query)stringoptional

<provider_label> or <provider_label>/<model>: rows that name it, following destination and failover-profile refs (adds references [paths]).

No request body.

curl --request GET \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/rate-limits?limit=example' \
  --header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules· Try it in the playground

DELETE/controls/rate-limits/{resource_id}

Delete a rate limit

Removes the rate limit; refused while other controls reference it. If-Match is required.

REQUIRESlimits:write

Path, query & header parameters 4

resource_id (path)stringrequired

Client-chosen control ID, ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$ (console rules read as console:<policy>:<rule_index>).

dry_run (query)booleanoptional

Preview: spec and policy diff, diagnostics, warnings, would_publish and impact; nothing is saved.

default: false

If-Match (header)stringrequired

Resource ETag "r<revision>-<id>-<hash8>" from the latest read, or the collection ETag "r<revision>". Required to change or delete an existing resource (428 when missing, 412 when stale); an unrelated publish does not invalidate it.

Idempotency-Key (header)stringoptional

Unique per logical write. A retry with the same key and body returns the original result, including after a crash once the revision was published. Optional on PUT, PATCH and DELETE.

min length: 1max length: 200

Full request body specification application/json

Unknown fields are rejected in this object.

curl --request DELETE \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/rate-limits/eu-pool' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'If-Match: "r12-eu-pool-1a2b3c4d"'

Authentication, errors & retry rules· Try it in the playground

GET/controls/rate-limits/{resource_id}

Read a rate limit

One rate limit and its ETag.

REQUIRESlimits:read

Path, query & header parameters 1

resource_id (path)stringrequired

Client-chosen control ID, ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$ (console rules read as console:<policy>:<rule_index>).

No request body.

curl --request GET \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/rate-limits/eu-pool' \
  --header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules· Try it in the playground

PATCH/controls/rate-limits/{resource_id}

Update a rate limit

JSON merge patch of the rate limit (null removes a field); the result is validated as a whole. If-Match is required. Writes publish one policy revision. A PUT whose content equals the stored resource returns changed false and publishes nothing.

REQUIRESlimits:write

Path, query & header parameters 4

resource_id (path)stringrequired

Client-chosen control ID, ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$ (console rules read as console:<policy>:<rule_index>).

dry_run (query)booleanoptional

Preview: spec and policy diff, diagnostics, warnings, would_publish and impact; nothing is saved.

default: false

If-Match (header)stringrequired

Resource ETag "r<revision>-<id>-<hash8>" from the latest read, or the collection ETag "r<revision>". Required to change or delete an existing resource (428 when missing, 412 when stale); an unrelated publish does not invalidate it.

Idempotency-Key (header)stringoptional

Unique per logical write. A retry with the same key and body returns the original result, including after a crash once the revision was published. Optional on PUT, PATCH and DELETE.

min length: 1max length: 200

Full request body specification application/json

A rate limit. Its quota id rl_<id> is customer-visible (the x-quilr-quota-id header of a refused request). metric, group_by and window are the counter's identity: they are ForceNew (changing them is 422 identity_field_immutable; create a rate limit with a new id).

adjustmentsobjectoptional

Required for temporary raises (grants).

Object fields

auto_approveobjectoptional

Object fields

max_countintegeroptional

min: 1max: 100

perstringoptional

"day""week""month"

smart_groupsarray<string>optional

max items: 32unique items

Array item specification

string

min length: 1

up_to_pctintegerrequired

min: 1max: 1000

Unknown fields are rejected in this object.

ceilingnumberrequired

min: 0

max_durationstringoptional

pattern: ^[1-9][0-9]{0,4}(h|d)$default: "366d"

overflowobjectoptional

Object fields

add_pctintegerrequired

min: 1max: 1000

Unknown fields are rejected in this object.

requestablebooleanoptional

default: false

Unknown fields are rejected in this object.

alertsarray<object>optional

max items: 5

Array item specification

at_pctintegerrequired

min: 1max: 100

Unknown fields are rejected in this object.

descriptionstringoptional

min length: 1max length: 500

familystringoptional

max length: 128pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$

group_byarray<string>optional

One counter per distinct combination; [] = one shared counter.

unique itemsdefault: []

Array item specification

string

A QuilrQL field name, or an alias (app = application.group_key, app_key = application.key_id, method = application.method_key, method_type = application.method_type, model = gateway.actual_model, provider = gateway.actual_provider.name, provider_label = gateway.actual_provider.label, smart_group = user.active_smart_group, tenant = tenant.id, user = user.email, user_id = user.id). Aliases are translated; responses return field names.

Values: "tenant.id""user.id""user.email""user.active_smart_group""application.key_id""application.group_key""application.method_key""application.method_type""gateway.actual_provider.name""gateway.actual_provider.label""gateway.actual_model""app""app_key""method""method_type""model""provider""provider_label""smart_group""tenant""user""user_id"

kind"rate"optional

labelstringoptional

min length: 1max length: 120

limitintegerrequired

min: 0

metricobjectrequired

"requests""input_tokens""output_tokens""total_tokens"

modeobjectoptional

default: "enforce"

"enforce""alert""paused"

overridesarray<string>optional

Rate quota ids this one replaces where both apply: managed rate limits (rl_<id>) or console quotas of kind rate. Budgets are 422 override_target_not_allowed.

min items: 1max items: 16unique items

Array item specification

string

max length: 128pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$

quota_idstringoptional

scopeobjectoptional

Every non-empty list must match (AND); empty or omitted lists do not restrict. Returned with every field present.

Object fields

app_tagsarray<string>optional

max items: 100unique items

Array item specification

string

min length: 1max length: 256

appsarray<string>optional

max items: 100unique items

Array item specification

string

min length: 1max length: 256

smart_groupsarray<string>optional

max items: 100unique items

Array item specification

string

min length: 1max length: 256

usersarray<string>optional

max items: 100unique items

Array item specification

string

min length: 1max length: 256

Unknown fields are rejected in this object.

windowone of 2 variantsrequired

Variant 1 object

kind"rolling"required

sizeintegeroptional

Window length in units (1 = omitted).

min: 1

unitobjectrequired

"minute""hour""day""week""month""year"

Unknown fields are rejected in this object.

Variant 2 object

kind"calendar"required

timezonestringoptional

IANA timezone.

default: "UTC"

unitobjectrequired

"day""month""week""year"

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

curl --request PATCH \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/rate-limits/eu-pool' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'If-Match: "r12-eu-pool-1a2b3c4d"'

Authentication, errors & retry rules· Try it in the playground

PUT/controls/rate-limits/{resource_id}

Create or replace a rate limit

Creates (201) or replaces (200) the rate limit. Changing an existing one needs If-Match; If-None-Match: * creates only. Writes publish one policy revision. A PUT whose content equals the stored resource returns changed false and publishes nothing.

REQUIRESlimits:write

Path, query & header parameters 5

resource_id (path)stringrequired

Client-chosen control ID, ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$ (console rules read as console:<policy>:<rule_index>).

dry_run (query)booleanoptional

Preview: spec and policy diff, diagnostics, warnings, would_publish and impact; nothing is saved.

default: false

If-Match (header)stringoptional

Resource ETag "r<revision>-<id>-<hash8>" from the latest read, or the collection ETag "r<revision>". Required to change or delete an existing resource (428 when missing, 412 when stale); an unrelated publish does not invalidate it.

Idempotency-Key (header)stringoptional

Unique per logical write. A retry with the same key and body returns the original result, including after a crash once the revision was published. Optional on PUT, PATCH and DELETE.

min length: 1max length: 200

If-None-Match (header)"*"optional

Create only: 412 when the resource exists with different content.

Full request body specification application/json

A rate limit. Its quota id rl_<id> is customer-visible (the x-quilr-quota-id header of a refused request). metric, group_by and window are the counter's identity: they are ForceNew (changing them is 422 identity_field_immutable; create a rate limit with a new id).

adjustmentsobjectoptional

Required for temporary raises (grants).

Object fields

auto_approveobjectoptional

Object fields

max_countintegeroptional

min: 1max: 100

perstringoptional

"day""week""month"

smart_groupsarray<string>optional

max items: 32unique items

Array item specification

string

min length: 1

up_to_pctintegerrequired

min: 1max: 1000

Unknown fields are rejected in this object.

ceilingnumberrequired

min: 0

max_durationstringoptional

pattern: ^[1-9][0-9]{0,4}(h|d)$default: "366d"

overflowobjectoptional

Object fields

add_pctintegerrequired

min: 1max: 1000

Unknown fields are rejected in this object.

requestablebooleanoptional

default: false

Unknown fields are rejected in this object.

alertsarray<object>optional

max items: 5

Array item specification

at_pctintegerrequired

min: 1max: 100

Unknown fields are rejected in this object.

descriptionstringoptional

min length: 1max length: 500

familystringoptional

max length: 128pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$

group_byarray<string>optional

One counter per distinct combination; [] = one shared counter.

unique itemsdefault: []

Array item specification

string

A QuilrQL field name, or an alias (app = application.group_key, app_key = application.key_id, method = application.method_key, method_type = application.method_type, model = gateway.actual_model, provider = gateway.actual_provider.name, provider_label = gateway.actual_provider.label, smart_group = user.active_smart_group, tenant = tenant.id, user = user.email, user_id = user.id). Aliases are translated; responses return field names.

Values: "tenant.id""user.id""user.email""user.active_smart_group""application.key_id""application.group_key""application.method_key""application.method_type""gateway.actual_provider.name""gateway.actual_provider.label""gateway.actual_model""app""app_key""method""method_type""model""provider""provider_label""smart_group""tenant""user""user_id"

kind"rate"optional

labelstringoptional

min length: 1max length: 120

limitintegerrequired

min: 0

metricobjectrequired

"requests""input_tokens""output_tokens""total_tokens"

modeobjectoptional

default: "enforce"

"enforce""alert""paused"

overridesarray<string>optional

Rate quota ids this one replaces where both apply: managed rate limits (rl_<id>) or console quotas of kind rate. Budgets are 422 override_target_not_allowed.

min items: 1max items: 16unique items

Array item specification

string

max length: 128pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$

quota_idstringoptional

scopeobjectoptional

Every non-empty list must match (AND); empty or omitted lists do not restrict. Returned with every field present.

Object fields

app_tagsarray<string>optional

max items: 100unique items

Array item specification

string

min length: 1max length: 256

appsarray<string>optional

max items: 100unique items

Array item specification

string

min length: 1max length: 256

smart_groupsarray<string>optional

max items: 100unique items

Array item specification

string

min length: 1max length: 256

usersarray<string>optional

max items: 100unique items

Array item specification

string

min length: 1max length: 256

Unknown fields are rejected in this object.

windowone of 2 variantsrequired

Variant 1 object

kind"rolling"required

sizeintegeroptional

Window length in units (1 = omitted).

min: 1

unitobjectrequired

"minute""hour""day""week""month""year"

Unknown fields are rejected in this object.

Variant 2 object

kind"calendar"required

timezonestringoptional

IANA timezone.

default: "UTC"

unitobjectrequired

"day""month""week""year"

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

curl --request PUT \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/rate-limits/eu-pool' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'If-Match: "r12-eu-pool-1a2b3c4d"' \
  --header 'Content-Type: application/json' \
  --data '{
  "adjustments": {
    "ceiling": 120,
    "max_duration": "2d"
  },
  "group_by": [
    "user.email"
  ],
  "label": "Support requests per minute",
  "limit": 60,
  "metric": "requests",
  "scope": {
    "apps": [
      "support-bot"
    ]
  },
  "window": {
    "kind": "rolling",
    "unit": "minute"
  }
}'

Authentication, errors & retry rules· Try it in the playground

GET/controls/rate-limits/{resource_id}/grants

List rate limit grants

Temporary raises of one rate limit.

REQUIRESlimits:read

Path, query & header parameters 1

resource_id (path)stringrequired

Client-chosen control ID, ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$ (console rules read as console:<policy>:<rule_index>).

No request body.

curl --request GET \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/rate-limits/eu-pool/grants' \
  --header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules· Try it in the playground

POST/controls/rate-limits/{resource_id}/grants

Grant a temporary raise

Raises one subject's limit until expires_at (extra adds to the limit, limit sets it), capped by the rate limit's adjustments. A new grant supersedes the bucket's previous one.

REQUIRESlimits:grant

Path, query & header parameters 2

resource_id (path)stringrequired

Client-chosen control ID, ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$ (console rules read as console:<policy>:<rule_index>).

Idempotency-Key (header)stringrequired

Unique per logical write. A retry with the same key and body returns the original result, including after a crash once the revision was published. Not needed with dry_run=true.

min length: 1max length: 200

Full request body specification application/json

A temporary raise for one bucket, capped by the rate limit's adjustments. A new grant supersedes the bucket's previous one. POST takes an Idempotency-Key; a retry returns the original grant.

Variant 1 object

object

Variant 2 object

object

curl --request POST \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/rate-limits/eu-pool/grants' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'Idempotency-Key: eu-routing-change-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "expires_at": "2026-11-01T00:00:00Z",
  "extra": 60,
  "reason": "launch",
  "subject": {
    "user": "alex@example.com"
  }
}'

Authentication, errors & retry rules· Try it in the playground

DELETE/controls/rate-limits/{resource_id}/grants/{grant_id}

Revoke a grant

Ends the grant now. If-Match (the grant ETag) is required.

REQUIRESlimits:grant

Path, query & header parameters 4

resource_id (path)stringrequired

Client-chosen control ID, ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$ (console rules read as console:<policy>:<rule_index>).

grant_id (path)stringrequired

If-Match (header)stringrequired

Grant ETag from the latest read (428 when missing, 412 when stale).

reason (query)stringoptional

Recorded with the revocation.

Full request body specification application/json

Unknown fields are rejected in this object.

curl --request DELETE \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/rate-limits/eu-pool/grants/grt_4f9a2c1b7e3d' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'If-Match: "3f1c0a9e5b7d"'

Authentication, errors & retry rules· Try it in the playground

GET/controls/rate-limits/{resource_id}/usage

Read rate limit usage

Live counters of one rate limit: one subject's bucket, or the busiest buckets.

REQUIRESlimits:read

Path, query & header parameters 5

resource_id (path)stringrequired

Client-chosen control ID, ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$ (console rules read as console:<policy>:<rule_index>).

subject.user (query)stringoptional

One user's bucket.

subject.app (query)stringoptional

One app's bucket.

bucket (query)stringoptional

A bucket in canonical form.

top (query)integeroptional

Busiest buckets listed when no subject is given.

min: 1max: 200default: 20

No request body.

curl --request GET \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/rate-limits/eu-pool/usage' \
  --header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules· Try it in the playground

POST/controls/rate-limits:migrate-legacy

Migrate legacy limits

Converts the deprecated per-app window limits to rate limits in one revision. dry_run=true previews the quotas and diff.

REQUIRESlimits:write

Path, query & header parameters 2

dry_run (query)booleanoptional

Preview: spec and policy diff, diagnostics, warnings, would_publish and impact; nothing is saved.

default: false

Idempotency-Key (header)stringrequired

Unique per logical write. A retry with the same key and body returns the original result, including after a crash once the revision was published. Not needed with dry_run=true.

min length: 1max length: 200

Full request body specification application/json

dry_runbooleanoptional

Unknown fields are rejected in this object.

curl --request POST \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/rate-limits:migrate-legacy' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'Idempotency-Key: eu-routing-change-001' \
  --header 'Content-Type: application/json' \
  --data '{}'

Authentication, errors & retry rules· Try it in the playground

Request guards

GET/controls/request-guards

List request guards

Every managed request guard with its ETag, then the console policy rules of the same kind as read-only rows (source console, policy, rule_index, view). Console rows cannot be written here (409 rule_not_api_managed). Paginated (limit, cursor bound to the revision) and filtered by source, app, requested_model, mode and references.

REQUIRESlimits:read

Path, query & header parameters 7

limit (query)integeroptional

Page size.

min: 1max: 500default: 100

cursor (query)stringoptional

next_cursor of the previous page; bound to the revision (409 collection_changed when the policy changed).

source (query)objectoptional

Only managed resources or only console rows.

"managed""console"

app (query)stringoptional

Rows that can apply to this app (rows scoped only by smart group, user or tag are kept). app_name is a deprecated alias.

requested_model (query)stringoptional

Rows that can apply to this requested model. model is a deprecated alias.

mode (query)stringoptional

Rows with this mode (routes: active, observe, disabled; limits: enforce, alert, paused).

references (query)stringoptional

<provider_label> or <provider_label>/<model>: rows that name it, following destination and failover-profile refs (adds references [paths]).

No request body.

curl --request GET \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/request-guards?limit=example' \
  --header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules· Try it in the playground

DELETE/controls/request-guards/{resource_id}

Delete a request guard

Removes the request guard; refused while other controls reference it. If-Match is required.

REQUIRESlimits:write

Path, query & header parameters 4

resource_id (path)stringrequired

Client-chosen control ID, ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$ (console rules read as console:<policy>:<rule_index>).

dry_run (query)booleanoptional

Preview: spec and policy diff, diagnostics, warnings, would_publish and impact; nothing is saved.

default: false

If-Match (header)stringrequired

Resource ETag "r<revision>-<id>-<hash8>" from the latest read, or the collection ETag "r<revision>". Required to change or delete an existing resource (428 when missing, 412 when stale); an unrelated publish does not invalidate it.

Idempotency-Key (header)stringoptional

Unique per logical write. A retry with the same key and body returns the original result, including after a crash once the revision was published. Optional on PUT, PATCH and DELETE.

min length: 1max length: 200

Full request body specification application/json

Unknown fields are rejected in this object.

curl --request DELETE \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/request-guards/eu-pool' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'If-Match: "r12-eu-pool-1a2b3c4d"'

Authentication, errors & retry rules· Try it in the playground

GET/controls/request-guards/{resource_id}

Read a request guard

One request guard and its ETag.

REQUIRESlimits:read

Path, query & header parameters 1

resource_id (path)stringrequired

Client-chosen control ID, ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$ (console rules read as console:<policy>:<rule_index>).

No request body.

curl --request GET \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/request-guards/eu-pool' \
  --header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules· Try it in the playground

PATCH/controls/request-guards/{resource_id}

Update a request guard

JSON merge patch of the request guard (null removes a field); the result is validated as a whole. If-Match is required. Writes publish one policy revision. A PUT whose content equals the stored resource returns changed false and publishes nothing.

REQUIRESlimits:write

Path, query & header parameters 4

resource_id (path)stringrequired

Client-chosen control ID, ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$ (console rules read as console:<policy>:<rule_index>).

dry_run (query)booleanoptional

Preview: spec and policy diff, diagnostics, warnings, would_publish and impact; nothing is saved.

default: false

If-Match (header)stringrequired

Resource ETag "r<revision>-<id>-<hash8>" from the latest read, or the collection ETag "r<revision>". Required to change or delete an existing resource (428 when missing, 412 when stale); an unrelated publish does not invalidate it.

Idempotency-Key (header)stringoptional

Unique per logical write. A retry with the same key and body returns the original result, including after a crash once the revision was published. Optional on PUT, PATCH and DELETE.

min length: 1max length: 200

Full request body specification application/json

Per-request token and timeout guards for the scoped requests; where several apply, the strictest value wins.

Variant 1 object

object

Variant 2 object

object

curl --request PATCH \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/request-guards/eu-pool' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'If-Match: "r12-eu-pool-1a2b3c4d"'

Authentication, errors & retry rules· Try it in the playground

PUT/controls/request-guards/{resource_id}

Create or replace a request guard

Creates (201) or replaces (200) the request guard. Changing an existing one needs If-Match; If-None-Match: * creates only. Writes publish one policy revision. A PUT whose content equals the stored resource returns changed false and publishes nothing.

REQUIRESlimits:write

Path, query & header parameters 5

resource_id (path)stringrequired

Client-chosen control ID, ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$ (console rules read as console:<policy>:<rule_index>).

dry_run (query)booleanoptional

Preview: spec and policy diff, diagnostics, warnings, would_publish and impact; nothing is saved.

default: false

If-Match (header)stringoptional

Resource ETag "r<revision>-<id>-<hash8>" from the latest read, or the collection ETag "r<revision>". Required to change or delete an existing resource (428 when missing, 412 when stale); an unrelated publish does not invalidate it.

Idempotency-Key (header)stringoptional

Unique per logical write. A retry with the same key and body returns the original result, including after a crash once the revision was published. Optional on PUT, PATCH and DELETE.

min length: 1max length: 200

If-None-Match (header)"*"optional

Create only: 412 when the resource exists with different content.

Full request body specification application/json

Per-request token and timeout guards for the scoped requests; where several apply, the strictest value wins.

Variant 1 object

object

Variant 2 object

object

curl --request PUT \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/request-guards/eu-pool' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'If-Match: "r12-eu-pool-1a2b3c4d"' \
  --header 'Content-Type: application/json' \
  --data '{
  "max_tokens_per_request": 8000,
  "scope": {
    "smart_groups": [
      "eng"
    ]
  },
  "timeout_s": 30
}'

Authentication, errors & retry rules· Try it in the playground

Model limits

GET/controls/model-limits

List model limits

Every managed model limit with its ETag, then the console policy rules of the same kind as read-only rows (source console, policy, rule_index, view). Console rows cannot be written here (409 rule_not_api_managed). Paginated (limit, cursor bound to the revision) and filtered by source, app, requested_model, mode and references.

REQUIRESlimits:read

Path, query & header parameters 7

limit (query)integeroptional

Page size.

min: 1max: 500default: 100

cursor (query)stringoptional

next_cursor of the previous page; bound to the revision (409 collection_changed when the policy changed).

source (query)objectoptional

Only managed resources or only console rows.

"managed""console"

app (query)stringoptional

Rows that can apply to this app (rows scoped only by smart group, user or tag are kept). app_name is a deprecated alias.

requested_model (query)stringoptional

Rows that can apply to this requested model. model is a deprecated alias.

mode (query)stringoptional

Rows with this mode (routes: active, observe, disabled; limits: enforce, alert, paused).

references (query)stringoptional

<provider_label> or <provider_label>/<model>: rows that name it, following destination and failover-profile refs (adds references [paths]).

No request body.

curl --request GET \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/model-limits?limit=example' \
  --header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules· Try it in the playground

DELETE/controls/model-limits/{resource_id}

Delete a model limit

Removes the model limit; refused while other controls reference it. If-Match is required.

REQUIRESlimits:write

Path, query & header parameters 4

resource_id (path)stringrequired

Client-chosen control ID, ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$ (console rules read as console:<policy>:<rule_index>).

dry_run (query)booleanoptional

Preview: spec and policy diff, diagnostics, warnings, would_publish and impact; nothing is saved.

default: false

If-Match (header)stringrequired

Resource ETag "r<revision>-<id>-<hash8>" from the latest read, or the collection ETag "r<revision>". Required to change or delete an existing resource (428 when missing, 412 when stale); an unrelated publish does not invalidate it.

Idempotency-Key (header)stringoptional

Unique per logical write. A retry with the same key and body returns the original result, including after a crash once the revision was published. Optional on PUT, PATCH and DELETE.

min length: 1max length: 200

Full request body specification application/json

Unknown fields are rejected in this object.

curl --request DELETE \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/model-limits/eu-pool' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'If-Match: "r12-eu-pool-1a2b3c4d"'

Authentication, errors & retry rules· Try it in the playground

GET/controls/model-limits/{resource_id}

Read a model limit

One model limit and its ETag.

REQUIRESlimits:read

Path, query & header parameters 1

resource_id (path)stringrequired

Client-chosen control ID, ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$ (console rules read as console:<policy>:<rule_index>).

No request body.

curl --request GET \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/model-limits/eu-pool' \
  --header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules· Try it in the playground

PATCH/controls/model-limits/{resource_id}

Update a model limit

JSON merge patch of the model limit (null removes a field); the result is validated as a whole. If-Match is required. Writes publish one policy revision. A PUT whose content equals the stored resource returns changed false and publishes nothing.

REQUIRESlimits:write

Path, query & header parameters 4

resource_id (path)stringrequired

Client-chosen control ID, ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$ (console rules read as console:<policy>:<rule_index>).

dry_run (query)booleanoptional

Preview: spec and policy diff, diagnostics, warnings, would_publish and impact; nothing is saved.

default: false

If-Match (header)stringrequired

Resource ETag "r<revision>-<id>-<hash8>" from the latest read, or the collection ETag "r<revision>". Required to change or delete an existing resource (428 when missing, 412 when stale); an unrelated publish does not invalidate it.

Idempotency-Key (header)stringoptional

Unique per logical write. A retry with the same key and body returns the original result, including after a crash once the revision was published. Optional on PUT, PATCH and DELETE.

min length: 1max length: 200

Full request body specification application/json

Per-request guards for individual models (provider_label scopes one to a provider). Window limits per model are rate limits with group_by ["model"].

descriptionstringoptional

min length: 1max length: 500

limitsarray<object | object>required

min items: 1max items: 100

Array item specification

Variant 1 object

object

Variant 2 object

object

scopeobjectoptional

Every non-empty list must match (AND); empty or omitted lists do not restrict. Returned with every field present.

Object fields

app_tagsarray<string>optional

max items: 100unique items

Array item specification

string

min length: 1max length: 256

appsarray<string>optional

max items: 100unique items

Array item specification

string

min length: 1max length: 256

smart_groupsarray<string>optional

max items: 100unique items

Array item specification

string

min length: 1max length: 256

usersarray<string>optional

max items: 100unique items

Array item specification

string

min length: 1max length: 256

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

curl --request PATCH \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/model-limits/eu-pool' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'If-Match: "r12-eu-pool-1a2b3c4d"'

Authentication, errors & retry rules· Try it in the playground

PUT/controls/model-limits/{resource_id}

Create or replace a model limit

Creates (201) or replaces (200) the model limit. Changing an existing one needs If-Match; If-None-Match: * creates only. Writes publish one policy revision. A PUT whose content equals the stored resource returns changed false and publishes nothing.

REQUIRESlimits:write

Path, query & header parameters 5

resource_id (path)stringrequired

Client-chosen control ID, ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$ (console rules read as console:<policy>:<rule_index>).

dry_run (query)booleanoptional

Preview: spec and policy diff, diagnostics, warnings, would_publish and impact; nothing is saved.

default: false

If-Match (header)stringoptional

Resource ETag "r<revision>-<id>-<hash8>" from the latest read, or the collection ETag "r<revision>". Required to change or delete an existing resource (428 when missing, 412 when stale); an unrelated publish does not invalidate it.

Idempotency-Key (header)stringoptional

Unique per logical write. A retry with the same key and body returns the original result, including after a crash once the revision was published. Optional on PUT, PATCH and DELETE.

min length: 1max length: 200

If-None-Match (header)"*"optional

Create only: 412 when the resource exists with different content.

Full request body specification application/json

Per-request guards for individual models (provider_label scopes one to a provider). Window limits per model are rate limits with group_by ["model"].

descriptionstringoptional

min length: 1max length: 500

limitsarray<object | object>required

min items: 1max items: 100

Array item specification

Variant 1 object

object

Variant 2 object

object

scopeobjectoptional

Every non-empty list must match (AND); empty or omitted lists do not restrict. Returned with every field present.

Object fields

app_tagsarray<string>optional

max items: 100unique items

Array item specification

string

min length: 1max length: 256

appsarray<string>optional

max items: 100unique items

Array item specification

string

min length: 1max length: 256

smart_groupsarray<string>optional

max items: 100unique items

Array item specification

string

min length: 1max length: 256

usersarray<string>optional

max items: 100unique items

Array item specification

string

min length: 1max length: 256

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

curl --request PUT \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/model-limits/eu-pool' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'If-Match: "r12-eu-pool-1a2b3c4d"' \
  --header 'Content-Type: application/json' \
  --data '{
  "limits": [
    {
      "max_tokens_per_request": 4000,
      "model": "gpt-4.1"
    }
  ]
}'

Authentication, errors & retry rules· Try it in the playground

Limit exemptions

GET/controls/limit-exemptions

List limit exemptions

Every managed limit exemption with its ETag, then the console policy rules of the same kind as read-only rows (source console, policy, rule_index, view). Console rows cannot be written here (409 rule_not_api_managed). Paginated (limit, cursor bound to the revision) and filtered by source, app, requested_model, mode and references.

REQUIRESlimits:read

Path, query & header parameters 7

limit (query)integeroptional

Page size.

min: 1max: 500default: 100

cursor (query)stringoptional

next_cursor of the previous page; bound to the revision (409 collection_changed when the policy changed).

source (query)objectoptional

Only managed resources or only console rows.

"managed""console"

app (query)stringoptional

Rows that can apply to this app (rows scoped only by smart group, user or tag are kept). app_name is a deprecated alias.

requested_model (query)stringoptional

Rows that can apply to this requested model. model is a deprecated alias.

mode (query)stringoptional

Rows with this mode (routes: active, observe, disabled; limits: enforce, alert, paused).

references (query)stringoptional

<provider_label> or <provider_label>/<model>: rows that name it, following destination and failover-profile refs (adds references [paths]).

No request body.

curl --request GET \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/limit-exemptions?limit=example' \
  --header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules· Try it in the playground

DELETE/controls/limit-exemptions/{resource_id}

Delete a limit exemption

Removes the limit exemption; refused while other controls reference it. If-Match is required.

REQUIRESlimits:write

Path, query & header parameters 4

resource_id (path)stringrequired

Client-chosen control ID, ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$ (console rules read as console:<policy>:<rule_index>).

dry_run (query)booleanoptional

Preview: spec and policy diff, diagnostics, warnings, would_publish and impact; nothing is saved.

default: false

If-Match (header)stringrequired

Resource ETag "r<revision>-<id>-<hash8>" from the latest read, or the collection ETag "r<revision>". Required to change or delete an existing resource (428 when missing, 412 when stale); an unrelated publish does not invalidate it.

Idempotency-Key (header)stringoptional

Unique per logical write. A retry with the same key and body returns the original result, including after a crash once the revision was published. Optional on PUT, PATCH and DELETE.

min length: 1max length: 200

Full request body specification application/json

Unknown fields are rejected in this object.

curl --request DELETE \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/limit-exemptions/eu-pool' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'If-Match: "r12-eu-pool-1a2b3c4d"'

Authentication, errors & retry rules· Try it in the playground

GET/controls/limit-exemptions/{resource_id}

Read a limit exemption

One limit exemption and its ETag.

REQUIRESlimits:read

Path, query & header parameters 1

resource_id (path)stringrequired

Client-chosen control ID, ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$ (console rules read as console:<policy>:<rule_index>).

No request body.

curl --request GET \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/limit-exemptions/eu-pool' \
  --header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules· Try it in the playground

PATCH/controls/limit-exemptions/{resource_id}

Update a limit exemption

JSON merge patch of the limit exemption (null removes a field); the result is validated as a whole. If-Match is required. Writes publish one policy revision. A PUT whose content equals the stored resource returns changed false and publishes nothing.

REQUIRESlimits:write

Path, query & header parameters 4

resource_id (path)stringrequired

Client-chosen control ID, ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$ (console rules read as console:<policy>:<rule_index>).

dry_run (query)booleanoptional

Preview: spec and policy diff, diagnostics, warnings, would_publish and impact; nothing is saved.

default: false

If-Match (header)stringrequired

Resource ETag "r<revision>-<id>-<hash8>" from the latest read, or the collection ETag "r<revision>". Required to change or delete an existing resource (428 when missing, 412 when stale); an unrelated publish does not invalidate it.

Idempotency-Key (header)stringoptional

Unique per logical write. A retry with the same key and body returns the original result, including after a crash once the revision was published. Optional on PUT, PATCH and DELETE.

min length: 1max length: 200

Full request body specification application/json

Exempts the scoped requests from rate limits only (kinds is always [rate]; budget exemptions use the budgets API).

expires_atstringoptional

Must be in the future.

format: date-time

familiesarray<string>optional

min items: 1max items: 64unique items

Array item specification

string

max length: 128pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$

kindsarray<object>optional

default: ["rate"]

Array item specification

object

Values: "rate"

quotasone of 2 variantsrequired

Variant 1 "all"

"all"

Variant 2 array<string>

array<string>

min items: 1max items: 64unique items

reasonstringrequired

min length: 1max length: 300

scopeobjectoptional

Every non-empty list must match (AND); empty or omitted lists do not restrict. Returned with every field present.

Object fields

app_tagsarray<string>optional

max items: 100unique items

Array item specification

string

min length: 1max length: 256

appsarray<string>optional

max items: 100unique items

Array item specification

string

min length: 1max length: 256

smart_groupsarray<string>optional

max items: 100unique items

Array item specification

string

min length: 1max length: 256

usersarray<string>optional

max items: 100unique items

Array item specification

string

min length: 1max length: 256

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

curl --request PATCH \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/limit-exemptions/eu-pool' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'If-Match: "r12-eu-pool-1a2b3c4d"'

Authentication, errors & retry rules· Try it in the playground

PUT/controls/limit-exemptions/{resource_id}

Create or replace a limit exemption

Creates (201) or replaces (200) the limit exemption. Changing an existing one needs If-Match; If-None-Match: * creates only. Writes publish one policy revision. A PUT whose content equals the stored resource returns changed false and publishes nothing.

REQUIRESlimits:write

Path, query & header parameters 5

resource_id (path)stringrequired

Client-chosen control ID, ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$ (console rules read as console:<policy>:<rule_index>).

dry_run (query)booleanoptional

Preview: spec and policy diff, diagnostics, warnings, would_publish and impact; nothing is saved.

default: false

If-Match (header)stringoptional

Resource ETag "r<revision>-<id>-<hash8>" from the latest read, or the collection ETag "r<revision>". Required to change or delete an existing resource (428 when missing, 412 when stale); an unrelated publish does not invalidate it.

Idempotency-Key (header)stringoptional

Unique per logical write. A retry with the same key and body returns the original result, including after a crash once the revision was published. Optional on PUT, PATCH and DELETE.

min length: 1max length: 200

If-None-Match (header)"*"optional

Create only: 412 when the resource exists with different content.

Full request body specification application/json

Exempts the scoped requests from rate limits only (kinds is always [rate]; budget exemptions use the budgets API).

expires_atstringoptional

Must be in the future.

format: date-time

familiesarray<string>optional

min items: 1max items: 64unique items

Array item specification

string

max length: 128pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$

kindsarray<object>optional

default: ["rate"]

Array item specification

object

Values: "rate"

quotasone of 2 variantsrequired

Variant 1 "all"

"all"

Variant 2 array<string>

array<string>

min items: 1max items: 64unique items

reasonstringrequired

min length: 1max length: 300

scopeobjectoptional

Every non-empty list must match (AND); empty or omitted lists do not restrict. Returned with every field present.

Object fields

app_tagsarray<string>optional

max items: 100unique items

Array item specification

string

min length: 1max length: 256

appsarray<string>optional

max items: 100unique items

Array item specification

string

min length: 1max length: 256

smart_groupsarray<string>optional

max items: 100unique items

Array item specification

string

min length: 1max length: 256

usersarray<string>optional

max items: 100unique items

Array item specification

string

min length: 1max length: 256

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

curl --request PUT \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/limit-exemptions/eu-pool' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'If-Match: "r12-eu-pool-1a2b3c4d"' \
  --header 'Content-Type: application/json' \
  --data '{
  "expires_at": "2027-01-01T00:00:00Z",
  "quotas": "all",
  "reason": "on call",
  "scope": {
    "users": [
      "oncall@example.com"
    ]
  }
}'

Authentication, errors & retry rules· Try it in the playground

Limit responses

GET/controls/limit-responses

List limit responses

Every managed limit response with its ETag, then the console policy rules of the same kind as read-only rows (source console, policy, rule_index, view). Console rows cannot be written here (409 rule_not_api_managed). Paginated (limit, cursor bound to the revision) and filtered by source, app, requested_model, mode and references.

REQUIRESlimits:read

Path, query & header parameters 7

limit (query)integeroptional

Page size.

min: 1max: 500default: 100

cursor (query)stringoptional

next_cursor of the previous page; bound to the revision (409 collection_changed when the policy changed).

source (query)objectoptional

Only managed resources or only console rows.

"managed""console"

app (query)stringoptional

Rows that can apply to this app (rows scoped only by smart group, user or tag are kept). app_name is a deprecated alias.

requested_model (query)stringoptional

Rows that can apply to this requested model. model is a deprecated alias.

mode (query)stringoptional

Rows with this mode (routes: active, observe, disabled; limits: enforce, alert, paused).

references (query)stringoptional

<provider_label> or <provider_label>/<model>: rows that name it, following destination and failover-profile refs (adds references [paths]).

No request body.

curl --request GET \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/limit-responses?limit=example' \
  --header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules· Try it in the playground

DELETE/controls/limit-responses/{resource_id}

Delete a limit response

Removes the limit response; refused while other controls reference it. If-Match is required.

REQUIRESlimits:write

Path, query & header parameters 4

resource_id (path)stringrequired

Client-chosen control ID, ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$ (console rules read as console:<policy>:<rule_index>).

dry_run (query)booleanoptional

Preview: spec and policy diff, diagnostics, warnings, would_publish and impact; nothing is saved.

default: false

If-Match (header)stringrequired

Resource ETag "r<revision>-<id>-<hash8>" from the latest read, or the collection ETag "r<revision>". Required to change or delete an existing resource (428 when missing, 412 when stale); an unrelated publish does not invalidate it.

Idempotency-Key (header)stringoptional

Unique per logical write. A retry with the same key and body returns the original result, including after a crash once the revision was published. Optional on PUT, PATCH and DELETE.

min length: 1max length: 200

Full request body specification application/json

Unknown fields are rejected in this object.

curl --request DELETE \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/limit-responses/eu-pool' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'If-Match: "r12-eu-pool-1a2b3c4d"'

Authentication, errors & retry rules· Try it in the playground

GET/controls/limit-responses/{resource_id}

Read a limit response

One limit response and its ETag.

REQUIRESlimits:read

Path, query & header parameters 1

resource_id (path)stringrequired

Client-chosen control ID, ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$ (console rules read as console:<policy>:<rule_index>).

No request body.

curl --request GET \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/limit-responses/eu-pool' \
  --header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules· Try it in the playground

PATCH/controls/limit-responses/{resource_id}

Update a limit response

JSON merge patch of the limit response (null removes a field); the result is validated as a whole. If-Match is required. Writes publish one policy revision. A PUT whose content equals the stored resource returns changed false and publishes nothing.

REQUIRESlimits:write

Path, query & header parameters 4

resource_id (path)stringrequired

Client-chosen control ID, ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$ (console rules read as console:<policy>:<rule_index>).

dry_run (query)booleanoptional

Preview: spec and policy diff, diagnostics, warnings, would_publish and impact; nothing is saved.

default: false

If-Match (header)stringrequired

Resource ETag "r<revision>-<id>-<hash8>" from the latest read, or the collection ETag "r<revision>". Required to change or delete an existing resource (428 when missing, 412 when stale); an unrelated publish does not invalidate it.

Idempotency-Key (header)stringoptional

Unique per logical write. A retry with the same key and body returns the original result, including after a crash once the revision was published. Optional on PUT, PATCH and DELETE.

min length: 1max length: 200

Full request body specification application/json

The response sent when a limit refuses a request. Two different responses must pin scope.apps to lists with no app in common (else 422 limit_response_conflict).

Variant 1 object

object

Variant 2 object

object

Variant 3 object

object

curl --request PATCH \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/limit-responses/eu-pool' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'If-Match: "r12-eu-pool-1a2b3c4d"'

Authentication, errors & retry rules· Try it in the playground

PUT/controls/limit-responses/{resource_id}

Create or replace a limit response

Creates (201) or replaces (200) the limit response. Changing an existing one needs If-Match; If-None-Match: * creates only. Writes publish one policy revision. A PUT whose content equals the stored resource returns changed false and publishes nothing.

REQUIRESlimits:write

Path, query & header parameters 5

resource_id (path)stringrequired

Client-chosen control ID, ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$ (console rules read as console:<policy>:<rule_index>).

dry_run (query)booleanoptional

Preview: spec and policy diff, diagnostics, warnings, would_publish and impact; nothing is saved.

default: false

If-Match (header)stringoptional

Resource ETag "r<revision>-<id>-<hash8>" from the latest read, or the collection ETag "r<revision>". Required to change or delete an existing resource (428 when missing, 412 when stale); an unrelated publish does not invalidate it.

Idempotency-Key (header)stringoptional

Unique per logical write. A retry with the same key and body returns the original result, including after a crash once the revision was published. Optional on PUT, PATCH and DELETE.

min length: 1max length: 200

If-None-Match (header)"*"optional

Create only: 412 when the resource exists with different content.

Full request body specification application/json

The response sent when a limit refuses a request. Two different responses must pin scope.apps to lists with no app in common (else 422 limit_response_conflict).

Variant 1 object

object

Variant 2 object

object

Variant 3 object

object

curl --request PUT \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/limit-responses/eu-pool' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'If-Match: "r12-eu-pool-1a2b3c4d"' \
  --header 'Content-Type: application/json' \
  --data '{
  "message": "Limit {limit} reached; resets {reset}",
  "retry": "never",
  "url": "https://help.example.com/limits"
}'

Authentication, errors & retry rules· Try it in the playground

Effective limits

GET/limits/effective

Read effective limits

Every quota, request guard and model limit that applies to an app, user and model, the binding one, exemptions and grants, with live counters.

REQUIRESlimits:read

Path, query & header parameters 6

app (query)stringoptional

App name.

user (query)stringoptional

User email.

requested_model (query)stringoptional

Requested model.

model (query)stringoptional

Deprecated alias of requested_model.

provider_label (query)stringoptional

Provider label of the target.

include_usage (query)booleanoptional

Add live counters.

default: true

No request body.

curl --request GET \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/limits/effective' \
  --header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules· Try it in the playground

Related

• Rate, token and budget limits - what limits count and what clients see.
• Budgets API - spend, request and token budgets with pricing and budget grants.
• Routing and failover API - the write, ETag and restore rules shared by every control.
• Management API - authentication, scopes, errors and retry rules.