API ReferenceLimit Policies

Retrieve a limit policy

Retrieve one policy with its live current_state.

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.

Path parameters

idstringRequiredformat: "uuid"
Limit policy id.

Response

The 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.

algorithmenumOptionalDefaults to balance_fixed_window

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

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).

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