⚡ Rate Limiter
Outbound API rate limiting for agents. Check if an action is allowed before making it.
How it works
The Rate Limiter uses a sliding window counter pattern with atomic check-and-increment. Each call to the check endpoint atomically increments a counter and compares it against your limit. If the counter exceeds the limit within the window, the request is blocked with a 429 response and a retryAfter value telling you how many seconds until the window resets.
Counters are stored in the KV Store with an internal __rl: prefix, so they share your KV key quota and auto-expire with the window.
Check a rate limit
curl -X POST https://www.agent-utils.com/api/rate-limit/check \
-H "x-api-key: au_your_key" \
-H "Content-Type: application/json" \
-d '{"key":"openai:calls","limit":100,"windowSeconds":3600}'
# Response (200 allowed)
{"success":true,"data":{"allowed":true,"count":1,"remaining":99,"resetAt":"2025-01-15T13:00:00Z"}}
# Response (429 blocked)
{"success":true,"data":{"allowed":false,"count":101,"remaining":0,"resetAt":"2025-01-15T13:00:00Z","retryAfter":2341}}
Reset a rate limit
curl -X POST https://www.agent-utils.com/api/rate-limit/reset \
-H "x-api-key: au_your_key" \
-H "Content-Type: application/json" \
-d '{"key":"openai:calls"}'
# Response
{"success":true,"data":{"key":"openai:calls","reset":true}}
Get rate limit status
curl https://www.agent-utils.com/api/rate-limit/openai:calls \
-H "x-api-key: au_your_key"
# Response
{"success":true,"data":{"key":"openai:calls","count":42,"remaining":58,"resetAt":"2025-01-15T13:00:00Z","windowExpired":false}}
Parameters
| Param | Endpoint | Type | Description |
|---|---|---|---|
| key | check, reset | string | Identifier for the rate limit counter |
| limit | check | number | Max requests allowed in the window (min 1) |
| windowSeconds | check | number | Sliding window duration in seconds (min 1) |
| key | status (URL) | string | URL-encoded key name (e.g. openai%3Acalls) |
Python
import requests
headers = {"x-api-key": "au_your_key"}
# Check rate limit before calling external API
resp = requests.post("https://www.agent-utils.com/api/rate-limit/check",
headers=headers, json={
"key": "openai:calls",
"limit": 100,
"windowSeconds": 3600
})
data = resp.json()["data"]
if data["allowed"]:
# Safe to make the external API call
call_openai()
else:
print(f"Rate limited. Retry after {data['retryAfter']}s")
# Reset counter
requests.post("https://www.agent-utils.com/api/rate-limit/reset",
headers=headers, json={"key": "openai:calls"})
Dependency
The Rate Limiter stores counters in the KV Store with an internal __rl: prefix. Rate limit counters count toward your KV key quota and auto-expire when the window elapses.