Rate limits

Limits keep one runaway script from hurting you or anyone else. Every request must fit its key's budget and its organization's budget for its class of operation; a few operations also count against a daily or hourly cap. The numbers are the same on every plan.

Per minute, by class

Each operation belongs to one class (the reference names it). Budgets are per rolling minute and shared by every server, so spreading requests across connections does not raise them. The burst column is how many requests a key can send back to back before the per second pace applies.

Most requests cost one unit, whatever their filters or batch size: a lead list with search costs 1 and a batch upsert costs 1 per request. Analytics reads cost 5. The table at the end lists every operation's class and cost.

Daily and hourly caps

These caps count a rolling window: 24 hours, or one hour for messages into one conversation. They come on top of your plan's own limits (DM caps, discovery tokens, custom fields, import size), which the API applies exactly as the app does.

Concurrency

Besides the rate, a key and an organization may have only a few requests in flight at once on each server:

A request over these answers 503 with Retry-After. Send requests in sequence or with low parallelism; there is nothing to gain from more.

Headers

Every response describes the most constrained budget that applied:

RateLimit-Limit: 600
RateLimit-Remaining: 597
RateLimit-Reset: 41
RateLimit-Policy: "key-write";q=600;w=60

• RateLimit-Limit: the budget of that bucket.
• RateLimit-Remaining: what is left in it.
• RateLimit-Reset: seconds until its window ends.
• RateLimit-Policy: which bucket it is, its quota q and its window w in seconds.
• Retry-After: on every 429 and 503, the seconds to wait.

429 or 503

Backing off

Respect Retry-After first. When it is absent, back off exponentially with full jitter:

async function callWithRetry(request, attempts = 5) {
  for (let i = 0; ; i++) {
    const res = await request();
    if (res.status !== 429 && res.status !== 503) return res;
    if (i === attempts - 1) return res;
    const retryAfter = Number(res.headers.get("retry-after"));
    const base = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : 500 * 2 ** i;
    await new Promise((r) => setTimeout(r, base + Math.random() * base));
  }
}

Reuse the same Idempotency-Key on every retry of a write (see Idempotency).

Fair share

When the whole platform is busy, each active organization's per minute budget shrinks to an equal share of the remaining capacity, so a single heavy user cannot crowd out the others. A refusal for this reason is a 429 whose RateLimit-Policy names fair-share; it lifts as soon as the load drops.

The five original endpoints

GET /v1/me, GET /v1/campaigns, POST /v1/leads, GET /v1/leads/lookup and POST /v1/campaign-leads, the endpoints the Clay integration has always used, keep the limits they have always had. A request to them is never refused for concurrency or for platform load, and none of the class budgets above applies. A row-by-row Clay table that worked before keeps working.

Over these, the answer is the same 429 these endpoints have always sent, with Retry-After.

Requests without a valid key

These limits apply only to traffic that does not authenticate. A request with a valid key is never throttled or blocked because of its IP address, so shared egress addresses (Clay, Zapier, Make, n8n, hosted agents) keep working whatever other tenants on them do.

Every operation