Skip to Content
Rate limits

Get rate limit rule

Get a rate limit rule by ID.

GET
/rate-limits/rules/{rule_id}

Get a rate limit rule by ID.

Authorization

ApiKeyAuth
headerAuthorizationBearer <token>

Bearer token authentication. Send an API key (a saai_api_-prefixed token) as Authorization: Bearer <token>.

Required permission

view_rate_limits

Path Parameters

rule_id*string
Formatuuid

Response Body

The request has succeeded.

application/json
  1. response

A throughput limit on MCP tool calls or on model calls through the LLM gateway; the scope picks which, and can't change once the rule exists. Every rule whose scope matches a call must have budget left, so rules compose rather than override one another — an org-wide ceiling and a tighter per-user one are both enforced. Counters live in each gateway process by default, so with several replicas the effective ceiling is the configured limit times the replica count; a deployment can instead share one counter across every process through NATS.

id*uuid
Formatuuid
name*string

Short label for the rule, shown in the rule list.

description?|

Optional note explaining what the rule protects against.

status?RuleStatus

Whether a rule takes part in evaluation.

Value in"active""draft""disabled"
scope*|

What a rule matches.

key_by*array<>

What a rule counts its budget per. Always includes org; add dimensions to subdivide that org-wide budget further, e.g. ["org", "user", "tool"] for a per-user-per-tool budget. Order does not matter — the list is canonicalised — but it must include org and be free of duplicates.

Items1 <= items
limit*integer

Calls, or tokens for a tokens rule, allowed per window.

Formatint32
Range1 <= value
unit?RateLimitUnit

What the budget counts. Defaults to requests. tokens is for model-call rules only: it counts input tokens, including cache writes but not cache reads, plus output tokens, charged once the call finishes, so the call that crosses the limit finishes and the next one is refused. A tokens rule takes no burst: the whole window_seconds is one window and limit is its total.

Value in"requests""tokens"
window_seconds*integer

Length of the window in seconds. Capped at one hour, the lifetime of the bucket that tracks it.

Formatint32
Range1 <= value <= 3600
burst?integer

How many calls may arrive at once before the rate applies. Also sets the granularity at which budget is released: each window admits max(burst, ceil(limit * min(1 minute, window_seconds) / window_seconds)) calls, and the window is however long that many calls take at the configured rate, never shorter than min(1 minute, window_seconds) — e.g. 1000/hour with no burst set derives a 61.2-second window admitting 17 calls, which is exactly 1000/hour. Defaults to 1. Must be at most limit. A tokens rule takes none.

Formatint32
Range0 <= value
action?RateLimitAction

What happens to a call once a rule's budget is spent.

Value in"deny""log_only"
created_at*string
Formatdate-time
updated_at*string
Formatdate-time
Example Request
curl -X GET 'https://your-org.aisecurity.services.us.connect.secureauth.com/api/v1/rate-limits/rules/497f6eca-6276-4993-bfeb-53cbbbba6f08'
Example Response
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "name": "string",  "description": "string",  "status": "active",  "scope": {    "type": "mcp_call",    "agent_slugs": [      "string"    ],    "agent_instance_ids": [      "bc3f18ff-0dcd-4cc7-8f61-6ca61814f10b"    ],    "user_ids": [      "2d98503d-4ab4-41bd-8fc6-78cc006fd2db"    ],    "groups": [      "string"    ],    "agent_slug_tag_ids": [      "e428595a-d9dd-4887-8327-2d9cad5b7425"    ],    "autonomous": true,    "mcp_ids": [      "c2c9208c-a7ac-41cc-84f1-8c1caec92987"    ],    "mcp_tag_ids": [      "17d4a46c-d971-4171-9a66-88ec59ce6eeb"    ],    "tool_tag_ids": [      "41068329-9b4f-4cc3-b249-3ec2a7a2cee8"    ],    "tool_patterns": [      "string"    ],    "condition": "string",    "condition_description": "string"  },  "key_by": [    "org"  ],  "limit": 1,  "unit": "requests",  "window_seconds": 1,  "burst": 0,  "action": "deny",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}