Rate limits
The Kenso API limits calls two ways: per workspace, by the kind of call, and per operation, for each API key. A call has to fit both.
The limits
Kenso limits API key calls per workspace: per minute by the kind of call, and per day for all calls together. The limits depend on your workspace's plan, and Kenso can set other limits for a workspace.
| Kind | Free | Standard | Elevated |
|---|---|---|---|
Read (GET), per minute | 600 | 3,000 | 12,000 |
Write (POST, PATCH, PUT, DELETE), per minute | 240 | 1,200 | 4,800 |
Bulk (bulk operations such as bulk-create, and imports), calls per minute | 24 | 120 | 480 |
| Heavy (search, exports, analytics, AI runs), per minute | 12 | 60 | 240 |
| Sensitive (API keys, members, billing, webhooks, integrations), per minute | 30 | 30 | 30 |
| All calls, per day | 200,000 | 1,000,000 | 4,000,000 |
| Items sent to bulk operations, per day | 200,000 | 1,000,000 | 4,000,000 |
The Free plan is on Free, the Premium, Done-for-you and Performance plans are on Elevated, and every other plan on Standard.
Every response reports the rate limit the request is closest to reaching, whether that is your plan's limit, your API key's own limit or a limit on the operation: RateLimit-Limit (the limit), RateLimit-Remaining (the requests left) and RateLimit-Reset (the seconds until it resets). A 429 from one of these limits carries the same three headers, with RateLimit-Remaining: 0, and Retry-After. Over your plan's limit, the response is 429 rate_limited, and its details names the class, limit and window you hit. A 429 quota_exceeded is a usage quota, not a rate limit: wait the Retry-After seconds. Spread bulk work over the day instead of sending it in bursts.
Responses to an API key also carry X-RateLimit-Remaining-Minute and X-RateLimit-Remaining-Day, your key's own counters. They are deprecated: read the RateLimit-* headers instead.
Each operation also has its own limit per API key, on top of the workspace limits, and some are much lower than the table. The operation's description states it, and its x-ken-rate-limit field gives it as limit calls per windowSeconds, with per saying what is counted: api_key, or ip on the few calls made without a key. Over an operation's own limit, the response is 429 rate_limited with the headers above, Retry-After and the error body.
Some operations also count each call against a quota that allows fewer calls than the operation's own limit, such as email finds. There, x-ken-rate-limit lists each such quota under quotas (its policy, what it counts per: workspace, user or ip, its limits per windowSeconds, and the plans whose limits differ) and states them in summary. Over a quota, the response is a 429 with Retry-After. Its code is quota_exceeded on most operations and rate_limited on some; each operation's Errors list names the code.
Each operation's own limit
Every operation's page in the reference shows its own limit under its endpoint: per API key, or per IP address on the few calls made without a key. Most are at least as high as the workspace limits, so the workspace limit is the one you meet first. Some operations that send, launch or start work are capped far lower.
These operations are capped under 100 calls a minute per API key, or per IP address where the table says so:
| Operation | Endpoint | Calls a minute |
|---|---|---|
| Start an enrichment run | POST /v1/campaigns/{campaignId}/enrichment-runs | 10 |
| Launch a campaign | POST /v1/campaigns/{campaignId}/launch | 10 |
| Retry failed enrichment | POST /v1/campaigns/{campaignId}/retry-enrichment | 10 |
| Start a CLI login | POST /v1/cli/logins | 10 per IP address |
| Create a contact export | POST /v1/contact-exports | 10 |
| Start a domain health check | POST /v1/domain-health-checks | 10 |
| Check a domain's nameservers | POST /v1/domains/{domainId}/check-nameservers | 10 |
| Verify a domain's tracking DNS | POST /v1/domains/{domainId}/verify-dns | 10 |
| Import SMTP inboxes | POST /v1/inbox-imports | 10 |
| Connect an SMTP inbox | POST /v1/inboxes | 10 |
| Verify an inbox connection | POST /v1/inboxes/{inboxId}/verify | 10 |
| Start an inbox connect session | POST /v1/inboxes/connect-sessions | 10 |
| Start a LinkedIn connect session | POST /v1/linkedin-accounts/connect-sessions | 10 |
| Start a placement test | POST /v1/placement-tests | 10 |
| Start an email thread | POST /v1/threads | 10 |
| Forward an email thread | POST /v1/threads/{threadId}/forward | 10 |
| Send a reply in a thread | POST /v1/threads/{threadId}/messages | 10 |
| Start a hosted WhatsApp connect or reconnect session | POST /v1/whatsapp-accounts/connect-sessions | 10 |
| Create a bug report | POST /v1/bug-reports | 20 |
| Add a note to a bug report | POST /v1/bug-reports/{bugReportId}/notes | 20 |
| Duplicate a campaign | POST /v1/campaigns/{campaignId}/duplicate | 20 |
| Create an access request | POST /v1/access-requests | 30 |
| Connect a CRM | POST /v1/crm-connections | 30 |
| Finish an OAuth connection | POST /v1/crm-connections/oauth/complete | 30 |
| Export job postings | POST /v1/job-postings/search/export | 30 |
| Share a saved list by email | POST /v1/saved-lists/{savedListId}/invites | 30 |
| Upload an image for a Facebook reply | POST /v1/threads/{threadId}/images | 30 |
| Create your sandbox and its first test key | POST /v1/sandboxes | 50 |
| Reset your sandbox to its seed data | POST /v1/sandboxes/{sandboxId}/reset | 50 |
| Create another test key for your sandbox | POST /v1/sandboxes/{sandboxId}/test-keys | 50 |
| Start an AI run | POST /v1/campaigns/{campaignId}/ai-runs | 60 |
| Score a campaign's contacts | POST /v1/campaigns/{campaignId}/scoring/run | 60 |
| Scan an import file | POST /v1/contact-imports/scans | 60 |
| Regenerate a contact's AI lines | POST /v1/contacts/{contactId}/ai-lines/regenerate | 60 |
| Rebuild the outbound site | POST /v1/outbound-site/refresh | 60 |
| Get an endpoint's signing secret | GET /v1/webhook-endpoints/{webhookEndpointId}/signing-secret | 60 |
| Rotate an endpoint's signing secret | POST /v1/webhook-endpoints/{webhookEndpointId}/signing-secret/rotate | 60 |
When you get a 429
- Wait the
Retry-Afterseconds, then send the request again. - No
Retry-Afterheader: wait a moment, and double the wait after each further429. - A workspace limit answers with the code
rate_limited. An operation's own limit, and the per-key and per-IP limits in front of the API, answer with a plain-text body or{ "error": "Rate limit exceeded" }instead of the error object. Branch on the status, not oncode. - Watch
RateLimit-Remainingand slow down before it runs out. - Retrying a write is safe only with an
Idempotency-Key: see Idempotency.
More guides
AuthenticationWorkspacesVersioningPaginationErrorsIdempotencyWebhooksChangelogAPI reference