Skip to Content

Get a limit policy

GEThttps://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.

HTTP
Authorization: Bearer $RESPAN_API_KEY

Path parameters

Parameter Type Required Description and constraints
id string Required
Limit policy id.
Format: uuid

Responses

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: #/components/schemas/LimitPolicy
id string Optional
Format: uuid
Read only
name string Optional
Human label.
scope string Optional
Display category (e.g. API Key, Model). Not used for matching.
scope_value string Optional
Identity 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 Optional
What the cap counts. cost is US dollars, token_count is total tokens, request_count is calls.
Allowed: "cost", "request_count", "token_count"
Default: cost
algorithm string Optional
balance_fixed_window is the shipped algorithm. token_bucket is reserved and not yet enforced.
Allowed: "balance_fixed_window"
Default: balance_fixed_window
period string or null Optional
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 string Optional
When a recurring window aligns. calendar resets on the boundary (e.g. the 1st of the month).
Allowed: "calendar", "first_event", "explicit_ts"
Default: calendar
anchor_at string or null Optional
Required when anchor is not calendar.
Format: date-time
effective_at string or null Optional
Active-range start. null = live since forever.
Format: date-time
expires_at string or null Optional
Active-range end. null = live until deactivated. Must be after effective_at.
Format: date-time
priority integer Optional
Higher is checked first.
Default: 0
is_active boolean Optional
Default: true
rules array<object> Optional
Any number of soft rules and at most one effective hard rule.
rules[] object Array item
Reference: #/components/schemas/LimitPolicyRule
rules[].trigger object Required in parent
Threshold condition. Common shape: {"counter": {"operator": "gte", "value": 10000}}.
Additional properties are allowed
rules[].severity string Required in parent
soft fires an alert without blocking; hard blocks the request with 429.
Allowed: "soft", "hard"
rules[].description string or null Optional
Shown in events and alert payloads.
rules[].is_active boolean Optional
Default: true
rules[].notification_method_id string or null Optional
Optional OrganizationNotificationMethod id to ping when this rule trips.
threshold_value number Optional
First hard-rule threshold; falls back to the largest soft threshold.
Read only
meter_definition_id string Optional
Stable hash of the policy identity. Same identity resolves to the same id across recreations.
Read only
current_state object Optional
Live counter for the current window instance.
Reference: #/components/schemas/LimitPolicyCurrentState
current_state.meter_id string Optional
-
current_state.interval_start integer or null Optional
Epoch seconds, inclusive.
current_state.interval_end integer or null Optional
Epoch seconds, exclusive.
current_state.current_value number Optional
Accumulated value in this window.
created_at string Optional
Format: date-time
Read only
updated_at string Optional
Format: date-time
Read 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
JSON
{ "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
JSON
{ "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"
      }
    }
  }
}