Get a limit policy
GET
https://api.respan.ai/api/limit-policies/{id}/Return the policy with its live current_state.
Servers
https://api.respan.ai: Respan API Server
Authentication
RespanApiKey
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.
HTTP scheme: bearer; format: Respan API key.
Authorization: Bearer $RESPAN_API_KEYPath parameters
Parameter Type Required Description and constraints
id string RequiredLimit policy id.
Format:
Format:
uuidResponses
200
The policy.
application/json
Field Type Requirement Description and constraints
$ object Body
A stored cap: watch a scope, measure a metric, refill on a cadence, and fire rules at thresholds.
Reference:
Reference:
#/components/schemas/LimitPolicyid string OptionalFormat:
Read only
uuidRead only
name string OptionalHuman label.
scope string OptionalDisplay category (e.g.
API Key, Model). Not used for matching.scope_value string OptionalIdentity to meter. For composites, a JSON list of values in
compose order.compose array<string> Optional
Empty for single-dimension policies. Members:
organization_id, api_key_id, user_id, customer_identifier, model, endpoint.compose[] string Array item-
metric string OptionalWhat the cap counts.
Allowed:
Default:
cost is US dollars, token_count is total tokens, request_count is calls.Allowed:
"cost", "request_count", "token_count"Default:
costalgorithm string Optionalbalance_fixed_window is the shipped algorithm. token_bucket is reserved and not yet enforced.Allowed:
"balance_fixed_window"Default:
balance_fixed_windowperiod string or null OptionalCadence. 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.anchor string OptionalWhen a recurring window aligns.
Allowed:
Default:
calendar resets on the boundary (e.g. the 1st of the month).Allowed:
"calendar", "first_event", "explicit_ts"Default:
calendaranchor_at string or null OptionalRequired when
Format:
anchor is not calendar.Format:
date-timeeffective_at string or null OptionalActive-range start.
Format:
null = live since forever.Format:
date-timeexpires_at string or null OptionalActive-range end.
Format:
null = live until deactivated. Must be after effective_at.Format:
date-timepriority integer OptionalHigher is checked first.
Default:
Default:
0is_active boolean OptionalDefault:
truerules array<object> Optional
Any number of soft rules and at most one effective hard rule.
rules[] object Array item
Reference:
#/components/schemas/LimitPolicyRulerules[].trigger object Required in parentThreshold condition. Common shape:
Additional properties are allowed
{"counter": {"operator": "gte", "value": 10000}}.Additional properties are allowed
rules[].severity string Required in parentsoft fires an alert without blocking; hard blocks the request with 429.Allowed:
"soft", "hard"rules[].description string or null OptionalShown in events and alert payloads.
rules[].is_active boolean OptionalDefault:
truerules[].notification_method_id string or null OptionalOptional OrganizationNotificationMethod id to ping when this rule trips.
threshold_value number OptionalFirst hard-rule threshold; falls back to the largest soft threshold.
Read only
Read only
meter_definition_id string OptionalStable hash of the policy identity. Same identity resolves to the same id across recreations.
Read only
Read only
current_state object Optional
Live counter for the current window instance.
Reference:
Reference:
#/components/schemas/LimitPolicyCurrentStatecurrent_state.meter_id string Optional-
current_state.interval_start integer or null OptionalEpoch seconds, inclusive.
current_state.interval_end integer or null OptionalEpoch seconds, exclusive.
current_state.current_value number OptionalAccumulated value in this window.
created_at string OptionalFormat:
Read only
date-timeRead only
updated_at string OptionalFormat:
Read only
date-timeRead only
OpenAPI response schema
{
"$ref": "#/components/schemas/LimitPolicy"
}403
The API key is missing, invalid or expired.
application/json
Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent-
OpenAPI response schema
{
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
}Example
{
"detail": "Your API key is invalid or expired, please check your API key in the platform settings."
}404
Limit policy not found.
application/json
Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent-
OpenAPI response schema
{
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
}Example
{
"detail": "No LimitPolicy matches the given query."
}OpenAPI source
The operation and referenced components below retain the complete OpenAPI definitions, including constraints and examples.
OpenAPI operation
{
"summary": "Get a limit policy",
"operationId": "retrieve_limit_policy",
"tags": [
"Limit Policies"
],
"description": "Return the policy with its live `current_state`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Limit policy id."
}
],
"responses": {
"200": {
"description": "The policy.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LimitPolicy"
}
}
}
},
"403": {
"$ref": "#/components/responses/InvalidApiKey"
},
"404": {
"description": "Limit policy not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
},
"example": {
"detail": "No LimitPolicy matches the given query."
}
}
}
}
},
"security": [
{
"RespanApiKey": []
}
]
}OpenAPI path metadata
{}Referenced OpenAPI components
{
"responses": {
"InvalidApiKey": {
"description": "The API key is missing, invalid or expired.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
},
"example": {
"detail": "Your API key is invalid or expired, please check your API key in the platform settings."
}
}
}
}
},
"schemas": {
"LimitPolicy": {
"type": "object",
"description": "A stored cap: watch a scope, measure a metric, refill on a cadence, and fire rules at thresholds.",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"readOnly": true
},
"name": {
"type": "string",
"description": "Human label."
},
"scope": {
"type": "string",
"description": "Display category (e.g. `API Key`, `Model`). Not used for matching."
},
"scope_value": {
"type": "string",
"description": "Identity to meter. For composites, a JSON list of values in `compose` order."
},
"compose": {
"type": "array",
"items": {
"type": "string"
},
"description": "Empty for single-dimension policies. Members: `organization_id`, `api_key_id`, `user_id`, `customer_identifier`, `model`, `endpoint`."
},
"metric": {
"type": "string",
"enum": [
"cost",
"request_count",
"token_count"
],
"default": "cost",
"description": "What the cap counts. `cost` is US dollars, `token_count` is total tokens, `request_count` is calls."
},
"algorithm": {
"type": "string",
"enum": [
"balance_fixed_window"
],
"default": "balance_fixed_window",
"description": "`balance_fixed_window` is the shipped algorithm. `token_bucket` is reserved and not yet enforced."
},
"period": {
"type": "string",
"nullable": true,
"description": "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."
},
"anchor": {
"type": "string",
"enum": [
"calendar",
"first_event",
"explicit_ts"
],
"default": "calendar",
"description": "When a recurring window aligns. `calendar` resets on the boundary (e.g. the 1st of the month)."
},
"anchor_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Required when `anchor` is not `calendar`."
},
"effective_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Active-range start. `null` = live since forever."
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Active-range end. `null` = live until deactivated. Must be after `effective_at`."
},
"priority": {
"type": "integer",
"default": 0,
"description": "Higher is checked first."
},
"is_active": {
"type": "boolean",
"default": true
},
"rules": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LimitPolicyRule"
},
"description": "Any number of soft rules and at most one effective hard rule."
},
"threshold_value": {
"type": "number",
"readOnly": true,
"description": "First hard-rule threshold; falls back to the largest soft threshold."
},
"meter_definition_id": {
"type": "string",
"readOnly": true,
"description": "Stable hash of the policy identity. Same identity resolves to the same id across recreations."
},
"current_state": {
"$ref": "#/components/schemas/LimitPolicyCurrentState"
},
"created_at": {
"type": "string",
"format": "date-time",
"readOnly": true
},
"updated_at": {
"type": "string",
"format": "date-time",
"readOnly": true
}
}
},
"LimitPolicyCurrentState": {
"type": "object",
"description": "Live counter for the current window instance.",
"properties": {
"meter_id": {
"type": "string"
},
"interval_start": {
"type": "integer",
"nullable": true,
"description": "Epoch seconds, inclusive."
},
"interval_end": {
"type": "integer",
"nullable": true,
"description": "Epoch seconds, exclusive."
},
"current_value": {
"type": "number",
"description": "Accumulated value in this window."
}
}
},
"LimitPolicyRule": {
"type": "object",
"required": [
"trigger",
"severity"
],
"properties": {
"trigger": {
"type": "object",
"additionalProperties": true,
"description": "Threshold condition. Common shape: `{\"counter\": {\"operator\": \"gte\", \"value\": 10000}}`."
},
"severity": {
"type": "string",
"enum": [
"soft",
"hard"
],
"description": "`soft` fires an alert without blocking; `hard` blocks the request with 429."
},
"description": {
"type": "string",
"description": "Shown in events and alert payloads.",
"nullable": true
},
"is_active": {
"type": "boolean",
"default": true
},
"notification_method_id": {
"type": "string",
"nullable": true,
"description": "Optional OrganizationNotificationMethod id to ping when this rule trips."
}
}
}
},
"securitySchemes": {
"RespanApiKey": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "Respan API key",
"description": "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.",
"x-fern-bearer": {
"name": "respanApiKey",
"env": "RESPAN_API_KEY"
}
}
}
}