Skip to navigation
API ReferenceAdminLimit policies

Create a limit policy

Create a usage cap. The policy takes effect immediately: alert rules notify, and block rules reject gateway requests with 429 once the cap is reached.

Authentication

AuthorizationBearer

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.

Request

This endpoint expects an object.
namestringRequired
scope_valuestringRequired

Identity to meter. For composites (compose length >= 2), a JSON list of values in compose order.

metricenumRequiredDefaults to cost

What the cap counts. cost is US dollars, token_count is total tokens, request_count is calls.

Allowed values:
ruleslist of objectsRequired
scopestringOptional
Display category. Not used for matching.
composelist of stringsOptional
algorithmenumOptionalDefaults to balance_fixed_window
Allowed values:
periodstring or nullOptional

Named bucket, integer-seconds string, or null for cumulative.

anchorenumOptionalDefaults to calendar
Allowed values:
anchor_atdatetime or nullOptional
effective_atdatetime or nullOptional
expires_atdatetime or nullOptional
priorityintegerOptionalDefaults to 0
is_activebooleanOptionalDefaults to true

Response

The created policy.
idstringOptionalRead-onlyformat: "uuid"
namestringOptional
Human label.
scopestringOptional

Display category (e.g. API Key, Model). Not used for matching.

scope_valuestringOptional

Identity to meter. For composites, a JSON list of values in compose order.

composelist of stringsOptional

Empty for single-dimension policies. Members: organization_id, api_key_id, user_id, customer_identifier, model, endpoint.

metricenumOptionalDefaults to cost

What the cap counts. cost is US dollars, token_count is total tokens, request_count is calls.

Allowed values:
algorithmenumOptionalDefaults to balance_fixed_window

balance_fixed_window is the shipped algorithm. token_bucket is reserved and not yet enforced.

Allowed values:
periodstring or nullOptional

Cadence. A named bucket (minute, hour, day, week, month), a positive integer of seconds as a string, or null for a cumulative (lifetime) cap that never resets.

anchorenumOptionalDefaults to calendar

When a recurring window aligns. calendar resets on the boundary (e.g. the 1st of the month).

Allowed values:
anchor_atdatetime or nullOptional

Required when anchor is not calendar.

effective_atdatetime or nullOptional

Active-range start. null = live since forever.

expires_atdatetime or nullOptional

Active-range end. null = live until deactivated. Must be after effective_at.

priorityintegerOptionalDefaults to 0
Higher is checked first.
is_activebooleanOptionalDefaults to true
ruleslist of objectsOptional
Any number of soft rules and at most one effective hard rule.
threshold_valuedoubleOptionalRead-only

First hard-rule threshold; falls back to the largest soft threshold.

meter_definition_idstringOptionalRead-only
Stable hash of the policy identity. Same identity resolves to the same id across recreations.
current_stateobjectOptional
Live counter for the current window instance.
created_atdatetimeOptionalRead-only
updated_atdatetimeOptionalRead-only

Errors

400
Bad Request Error
403
Forbidden Error