Rate Limits

Limits by tier

The counter resets on a rolling 60-minute window, not at a fixed clock hour. Each API key has its own counter — keys on the same account do not share a quota.

The 429 response

When you exceed your limit, BriefGate returns HTTP 429:

{
  "error": "rate_limited",
  "message": "Rate limit of 60 requests/hour for the free plan reached. Retry after 1847s, or reduce polling frequency — use webhooks instead of polling get_intake_status in a loop.",
  "request_id": "req_abc123"
}

The Retry-After response header contains the number of seconds to wait before retrying. Respect this header rather than polling with a fixed interval.

The agent-loop problem

Agents running in a loop can exhaust the Free plan's 60 req/h limit in minutes if they call get_intake_status on every iteration. An agent checking status every 5 seconds makes 720 requests per hour — 12x the Free limit.

The correct approach is webhooks. Register a webhook endpoint for intake.completed and item.submitted. BriefGate calls your endpoint when something changes. You call BriefGate only when you need to act on a change.

With webhooks:

• Zero polling requests while waiting for client action
• Near-instant notification when the client submits
• Agent wakes up, calls get_intake_results once, continues building

Register a webhook endpoint:

curl -X POST https://api.briefgate.dev/v1/webhooks \
  -H "Authorization: Bearer bg_live_xxxxx" \
  -d '{"url":"https://yourapp.com/webhooks","events":["intake.completed","item.submitted"]}'

See Webhooks for the full setup guide.

Recommended polling intervals

If webhooks are not available for your deployment (e.g., running locally without a public URL), poll at these maximum rates to stay within limits with headroom for other API calls:

Use ngrok or a similar tunneling tool to expose a local webhook endpoint during development.

Rate limit scope

Rate limits are per API key, not per account.

• Multiple keys on the same account each have their own independent counter
• Use separate API keys for different agent sessions and CI pipelines — they will not interfere with each other
• Create additional keys at GET /v1/auth/keys (list) and POST /v1/auth/keys (create)

For example: one key for your Claude Code agent sessions, another for your CI deployment pipeline, another for webhook verification scripts.

Test mode keys

Keys starting with bg_test_ use a separate rate limit bucket. They do not consume production quota and work against the test intake environment.

Test keys return synthetic data and do not send real emails to clients. Use them for development and CI.

# Test key — safe to use in automated tests, does not hit production limits
BRIEFGATE_API_KEY=bg_test_xxxxx

Switch to a bg_live_ key when deploying to production.