Rate Limits

Limits by tier

The window is a fixed clock hour: the counter resets at the top of every hour, not 60 minutes after your first request. A burst just before the hour and another just after therefore both go through.

The counter belongs to the account, not to the individual API key. Issuing more keys does not raise your quota — all keys on an account draw from the same hourly budget.

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 account, not per API key.

• Every key on the account draws from the same hourly counter, so creating more keys does not raise the limit
• Use separate keys for different agent sessions and CI pipelines anyway: each can be revoked on its own, and the keys page shows which one was used last
• Create additional keys at GET /v1/keys (list) and POST /v1/keys (create), or sign a tool in without pasting a key (see the quickstart)