Core concepts

Rate limits

Each key can make 120 requests a minute, and every response says how many are left.

Limits

Limit	Applies to
120 requests a minute	Each API key, on every endpoint. The minute is a fixed window that starts on the minute.
10 exports an hour	Each account, on Create an export. Over it, 429 `export_rate_limit_exceeded`.
10 DMs a minute	Each X account, on Send a message. Over it, 429 `dm_rate_limited`.
300 DMs a day	Each X account, by UTC day, or less when X sets a lower quota. Over it, 429 `dm_daily_limit`.
5 passcode tries an hour	Each account, on Set the X Chat passcode. Over it, 429 `passcode_rate_limited`.
6 Julien AI messages a minute	Each X account, on Send a message and the MCP tool `ask_julien_ai`. Over it, 429 `assistant_rate_limited`.
100 Julien AI messages a day	Each X account, by UTC day. Over it, 429 `assistant_daily_limit`.
One Julien AI message at a time	Each chat, and 3 chats at once for each X account. Over it, 409 `assistant_busy`.

Rate limit headers

Every response carries the state of the key's window.

Header	Meaning
`RateLimit-Limit`	Requests allowed in a window, `120`.
`RateLimit-Remaining`	Requests left in the current window.
`RateLimit-Reset`	Seconds until the window starts again.
`Retry-After`	On a 429 only, seconds to wait before trying again.

Headers

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 17
Retry-After: 17
Request-Id: req_3Vb8YzC1dF6hJ0sW

Response429

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. This key can make 120 requests a minute.",
    "param": null,
    "request_id": "req_3Vb8YzC1dF6hJ0sW",
    "doc_url": "https://gemlead.ai/docs/errors#rate_limit_exceeded"
  }
}

Handle a 429

Wait for Retry-After seconds, then send the same request again.

Spread big jobs over time instead of sending them in bursts.
Read RateLimit-Remaining to slow down before you reach zero.
To pull many leads at once, one export beats hundreds of pages.
Webhooks push events to you, so you never spend requests polling for new leads.

# curl waits for Retry-After, then tries again
curl --retry 5 https://gemlead.ai/api/v1/leads \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"