Rate Limits

Per-endpoint Classic API rate limits, response headers, and retry guidance.

Every Amigo API endpoint enforces a rate limit, tracked per authenticated identity per endpoint. When you exceed the limit, the API returns HTTP 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying.

Classic API tables. The endpoint tables on this page cover Classic API endpoints (api.amigo.ai). Platform API endpoints enforce rate limits too - their per-endpoint limits are documented in the Platform API OpenAPI spec and the API reference documentation. See the Platform API guide for that surface.

Overview

The two API surfaces expose different rate-limit headers. Classic API responses expose only Retry-After, and only on 429 responses. Platform API responses include the X-RateLimit-* headers on every response.

Header	API	Description
Retry-After	Classic and Platform	Seconds to wait before retrying (present on 429 responses)
X-RateLimit-Limit	Platform only	Maximum requests allowed in the current window
X-RateLimit-Remaining	Platform only	Requests remaining in the current window
X-RateLimit-Reset	Platform only	UTC epoch seconds when the window resets

Rate limits are tracked per authenticated identity per endpoint, not pooled across the organization. On the Classic API, each request counts against the budget of the user the token was issued for - API keys are exchanged for user-scoped tokens, so keys that sign in as different users have independent budgets, while multiple keys signing in as the same user share that user's budget. On the Platform API, each API key has its own per-endpoint budget.

Rate Limits by Endpoint

Organization

Endpoint	Method	Rate Limit
/v1/{org}/organization/	PUT	5/min
/v1/{org}/organization/	POST	10/min
/v1/{org}/organization/	DELETE	5/min
/v1/{org}/organization/user_dimensions/	GET	20/min

Agent

Endpoint	Method	Rate Limit
/v1/{org}/organization/agent	POST	10/min
/v1/{org}/organization/agent	GET	20/min
/v1/{org}/organization/agent/{agent_id}/	POST	10/min
/v1/{org}/organization/agent/{agent_id}/	DELETE	10/min
/v1/{org}/organization/agent/{agent_id}/version	GET	20/min

API Keys

Endpoint	Method	Rate Limit
/v1/{org}/organization/api_key/	POST	5/min
/v1/{org}/organization/api_key/	GET	10/min
/v1/{org}/organization/api_key/{api_key_id}/	DELETE	10/min

Context Graphs (Service Hierarchical State Machines)

Endpoint	Method	Rate Limit
/v1/{org}/organization/service_hierarchical_state_machine	POST	10/min
/v1/{org}/organization/service_hierarchical_state_machine	GET	20/min
/v1/{org}/organization/service_hierarchical_state_machine/{id}/	POST	10/min
/v1/{org}/organization/service_hierarchical_state_machine/{id}/version	GET	20/min
/v1/{org}/organization/service_hierarchical_state_machine/{id}/	DELETE	10/min

Users

Endpoint	Method	Rate Limit
/v1/{org}/user/	POST	50/min
/v1/{org}/user/	GET	60/min
/v1/{org}/user/search/	GET	50/min
/v1/{org}/user/signin_with_api_key	POST	5/min
/v1/{org}/user/{requested_user_id}	POST	50/min
/v1/{org}/user/{requested_user_id}	DELETE	500/min
/v1/{org}/user/{requested_user_id}/variable	POST	50/min
/v1/{org}/user/{user_id}/memory	GET	40/min
/v1/{org}/user/{user_id}/user_model	GET	60/min

Services

Endpoint	Method	Rate Limit
/v1/{org}/service/	GET	50/min
/v1/{org}/service/	POST	20/min
/v1/{org}/service/{service_id}/	POST	20/min
/v1/{org}/service/{service_id}/version_sets/{version_set_name}/	PUT	30/min
/v1/{org}/service/{service_id}/version_sets/{version_set_name}/	DELETE	30/min

Conversations

Endpoint	Method	Rate Limit
/v1/{org}/conversation/	POST	5/min
/v1/{org}/conversation/	GET	15/min
/v1/{org}/conversation/conversation_starter	POST	10/min
/v1/{org}/conversation/{conversation_id}/finish/	POST	5/min
/v1/{org}/conversation/{conversation_id}/interact	POST	10/min
/v1/{org}/conversation/{conversation_id}/interaction/{interaction_id}/insights	GET	20/min
/v1/{org}/conversation/{conversation_id}/interaction/{interaction_id}/recommend_responses	POST	20/min
/v1/{org}/conversation/{conversation_id}/messages/	GET	20/min
/v1/{org}/conversation/{conversation_id}/messages/{message_id}/source	GET	30/min
/v1/{org}/conversation/{conversation_id}/tags/	POST	50/min

Tools (Actions)

Endpoint	Method	Rate Limit
/v1/{org}/tool/	POST	20/min
/v1/{org}/tool/	GET	50/min
/v1/{org}/tool/amigo_tool_scaffold.tar.gz	GET	50/min
/v1/{org}/tool/invocation	GET	50/min
/v1/{org}/tool/invocation/search	GET	50/min
/v1/{org}/tool/test	POST	1/min
/v1/{org}/tool/{tool_id}	POST	20/min
/v1/{org}/tool/{tool_id}	DELETE	20/min
/v1/{org}/tool/{tool_id}/envvar	POST	20/min
/v1/{org}/tool/{tool_id}/version	POST	10/min
/v1/{org}/tool/{tool_id}/version	GET	50/min
/v1/{org}/tool/{tool_id}/version/{versions}	DELETE	20/min
/v1/{org}/tool/{tool_id}/version/{version}/invoke	POST	10/min

Dynamic Behaviors

Endpoint	Method	Rate Limit
/v1/{org}/dynamic_behavior_set/	POST	200/min
/v1/{org}/dynamic_behavior_set/	GET	500/min
/v1/{org}/dynamic_behavior_set/search	GET	50/min
/v1/{org}/dynamic_behavior_set/{id}/	POST	500/min
/v1/{org}/dynamic_behavior_set/{id}/	DELETE	500/min
/v1/{org}/dynamic_behavior_set/{id}/invocation/	GET	50/min
/v1/{org}/dynamic_behavior_set/{id}/version/	POST	200/min
/v1/{org}/dynamic_behavior_set/{id}/version/	GET	1000/min

Metrics

Endpoint	Method	Rate Limit
/v1/{org}/metric/	POST	100/min
/v1/{org}/metric/	GET	20/min
/v1/{org}/metric/evaluate	POST	50/min
/v1/{org}/metric/metric_evaluation_result	GET	500/min
/v1/{org}/metric/search/	GET	20/min
/v1/{org}/metric/{metric_id}/	POST	20/min
/v1/{org}/metric/{metric_id}/	DELETE	100/min
/v1/{org}/metric/{metric_id}/version	GET	60/min
/v1/{org}/metric/{metric_id}/version/	POST	60/min

Roles & Permissions

Endpoint	Method	Rate Limit
/v1/{org}/role/	POST	20/min
/v1/{org}/role/	GET	20/min
/v1/{org}/role/temporary_permission_grant/	POST	100/min
/v1/{org}/role/temporary_permission_grants/	GET	100/min
/v1/{org}/role/{role_name}	POST	10/min
/v1/{org}/role/{role_name}/assign	POST	1000/min

Simulations

Personas

Endpoint	Method	Rate Limit
/v1/{org}/simulation/persona/	POST	100/min
/v1/{org}/simulation/persona/	GET	50/min
/v1/{org}/simulation/persona/search	GET	50/min
/v1/{org}/simulation/persona/{id}/	POST	100/min
/v1/{org}/simulation/persona/{id}/	DELETE	100/min
/v1/{org}/simulation/persona/{id}/version/	POST	100/min
/v1/{org}/simulation/persona/{id}/version/	GET	50/min

Scenarios

Endpoint	Method	Rate Limit
/v1/{org}/simulation/scenario/	POST	500/min
/v1/{org}/simulation/scenario/	GET	200/min
/v1/{org}/simulation/scenario/search	GET	50/min
/v1/{org}/simulation/scenario/{id}/	POST	500/min
/v1/{org}/simulation/scenario/{id}/	DELETE	500/min
/v1/{org}/simulation/scenario/{id}/version/	POST	500/min
/v1/{org}/simulation/scenario/{id}/version/	GET	500/min

Unit Tests

Endpoint	Method	Rate Limit
/v1/{org}/simulation/unit_test/	POST	500/min
/v1/{org}/simulation/unit_test/	GET	200/min
/v1/{org}/simulation/unit_test/search/	GET	50/min
/v1/{org}/simulation/unit_test/{id}/	POST	500/min
/v1/{org}/simulation/unit_test/{id}/	DELETE	500/min

Unit Test Sets & Runs

Endpoint	Method	Rate Limit
/v1/{org}/simulation/unit_test_set/	POST	50/min
/v1/{org}/simulation/unit_test_set/	GET	50/min
/v1/{org}/simulation/unit_test_set/search/	GET	50/min
/v1/{org}/simulation/unit_test_set/{id}	POST	50/min
/v1/{org}/simulation/unit_test_set/{id}	DELETE	50/min
/v1/{org}/simulation/unit_test_set_run/	POST	20/min
/v1/{org}/simulation/unit_test_set_run/	GET	50/min
/v1/{org}/simulation/unit_test_set_run/{id}/	DELETE	10/min
/v1/{org}/simulation/unit_test_set_run/{id}/artifacts/	GET	100/min

Webhook Destinations

Endpoint	Method	Rate Limit
/v1/{org}/webhook_destination/	POST	20/min
/v1/{org}/webhook_destination/	GET	20/min
/v1/{org}/webhook_destination/{id}	POST	20/min
/v1/{org}/webhook_destination/{id}	DELETE	20/min
/v1/{org}/webhook_destination/{id}/delivery	GET	5/min
/v1/{org}/webhook_destination/{id}/rotate-secret	POST	20/min

Admin

Endpoint	Method	Rate Limit
/v1/{org}/admin/get_models/	GET	20/min
/v1/{org}/admin/get_prompt_logs/	GET	20/min
/v1/{org}/admin/sql_query	POST	6/min

Handling Rate Limits

When your application receives a 429 response, use the Retry-After header to determine how long to wait. Combine this with exponential backoff for resilience.

Manual Implementation

Python

import requests, time

def request_with_backoff(method, url, headers, json=None, max_retries=5):
    delay = 1
    for attempt in range(1, max_retries + 1):
        resp = requests.request(method, url, headers=headers, json=json)
        if resp.status_code != 429:
            resp.raise_for_status()
            return resp
        # Respect Retry-After when present; otherwise fall back to exponential backoff
        retry_after = int(resp.headers.get("Retry-After", delay))
        print(f"Rate limited. Retrying in {retry_after}s (attempt {attempt}/{max_retries})")
        time.sleep(retry_after)
        delay = min(delay * 2, 60)
    raise RuntimeError("Exceeded maximum retry attempts due to rate limiting")

TypeScript

SDK Automatic Retry Behavior

Both the Python SDK (amigo-sdk) and TypeScript SDK (@amigo-ai/sdk) handle 429 responses automatically:

• The SDKs read the Retry-After header and wait the specified duration before retrying.
• Retries use exponential backoff for consecutive 429 responses.
• Network errors and 5xx server errors are also retried automatically.

No manual retry code needed when using the SDKs. The built-in retry logic handles rate limiting transparently. See Error Handling for details on configuring retry behavior.

Best Practices

1. Respect Retry-After headers. Always use the server-provided delay rather than a fixed wait time.
2. Use exponential backoff. If the Retry-After header is absent, double the delay on each consecutive 429 (capped at 60 seconds).
3. Monitor X-RateLimit-Remaining on the Platform API. Proactively slow down requests as you approach the limit rather than waiting for a 429. Classic API responses do not expose a remaining-request header, so rely on backoff there.
4. Batch where possible. Some endpoints (such as tool invocation) accept multiple items in a single request, reducing the number of calls.
5. Spread requests over time. Avoid bursting all requests at the start of a rate-limit window.
6. Use the SDKs. The official Python and TypeScript SDKs handle 429 retries automatically with proper backoff.
7. Design for the tightest limit. Conversation creation and interaction are limited to 5 and 10 requests/min respectively. Architect your application to stay comfortably within these bounds.