Limits & Quotas
The numeric limits the API enforces, in one place. Every value here is the current default; where a limit is tunable per environment the default is what a standard account sees. Each row links to the page that documents the behavior in context.
Rate limits
Every authenticated request is metered against a named bucket, keyed per
caller token (two API clients of the same company get independent buckets). A
request over the limit returns 429
with a Retry-After header.
| Bucket | Limit | Applies to |
|---|---|---|
| Read | 120 requests/min | Every GET (resource reads, reference lookups, polling). |
| Write | 30 requests/min | Every create and delete (POST). |
| MCP endpoint | 120 requests/min | Requests to POST /api/v2/mcp itself. Proxied sub-requests also consume the read/write buckets. |
Build budget
Every create that starts a worker job - audiences, estimates, Lookalike Models,
cohorts and activations - counts against one rolling budget per
organization, on every channel (console, API and MCP alike). Scheduled
replays do not count. Over the budget, the create is refused with
429 and a Retry-After header;
nothing is created.
| Window | Default | Notes |
|---|---|---|
| Rolling hour | 60 builds | Counted from the rows created in the last 60 minutes. |
| Rolling day | 300 builds | Counted from the rows created in the last 24 hours. |
Both values can be raised per organization by your Intuizi representative.
GET /api/v2/usage returns build_budget with the limits, the live counts and
retry_after_seconds when a window is exhausted, so a client can pace itself
before hitting 429.
Authentication
| Limit | Value | Notes |
|---|---|---|
| Login rate | 180 requests/min per IP | POST /api/v2/auth/login, metered per client IP, not per token. |
| Failed logins per email and IP | 5 per minute | Login and the API and MCP token mint and revoke endpoints share the count. Past it, they answer 429 with Retry-After for that email. A successful login clears it. See Failed logins. |
| Failed logins per email | 20 per hour | The failures for that email from any IP address. A successful login does not clear it. |
| MCP token mint / revoke rate | 10 requests/min per IP | POST /api/v2/auth/mcp-token and .../revoke. |
| Active MCP tokens | 10 per user | Further mints return 422 until you revoke one. |
| MCP token lifetime | 1 year | Manual MCP tokens expire after 365 days by default. |
| API token mint / revoke rate | 10 requests/min per IP | POST /api/v2/auth/api-token and .../revoke. |
| Active API tokens | 10 per user | Further mints return 422 until you revoke one. |
| API token lifetime | 1 year | API tokens expire after 365 days by default. |
See Authentication.
Idempotency
| Limit | Value | Notes |
|---|---|---|
| Replay TTL | 24 hours | How long a stored create response is replayable. |
Endpoints honoring Idempotency-Key | 7 creates | See the full list on Idempotency. |
Uploads
| Limit | Value | Notes |
|---|---|---|
| POI submission file | 50 MB | Max size for a poi_submission upload. |
| Cohort file | 1 GB | Max size for a cohort upload. |
| Presigned URL expiry | 15 minutes | Window, from reserving the slot, to PUT the file and to claim the reference with a create. |
| Unclaimed upload cleanup | 24 hours | An unclaimed object is removed after this horizon. It does not extend the window to claim the reference. |
| Open uploads | 20 per organization | Reservations that no create has used up and that have not expired. Past the limit, Create an Upload answers 429 with Retry-After, the seconds until the first of them expires, and reserves nothing. |
See Uploads.
POI submissions
| Limit | Value | Notes |
|---|---|---|
| Lookups a file gets by itself | 10,000 per file or list | Lookups of locations without coordinates, of the countries and address fields of locations with coordinates, and checks of locations with their coordinates and whole address, in that order and in the order of the file. Past them, the rest waits for Intuizi’s team: no file is refused for its size. See Files past the limit. |
Webhooks
| Limit | Value | Notes |
|---|---|---|
| Delivery attempts | 6 | Attempt 1 is immediate, then 5 retries. |
| Retry backoff | 1 min, 5 min, 25 min, 2 h, 6 h | Waits between attempts; the 6 attempts span roughly 8.5 hours. |
| Auto-disable threshold | 20 consecutive exhausted deliveries | The endpoint is switched off and its creator notified. |
| Signature timestamp tolerance | 5 minutes | The replay window receivers should enforce on the signed timestamp. |
See Webhooks and Webhooks API.
Audiences and Lookalike Models
| Limit | Value | Notes |
|---|---|---|
| Minimum to activate | 500 unique devices | Below this, an activation is rejected (is_activation_allowed is false). |
| Affinity device coverage | unique EIDs > 2x unique SCIDs | Audiences with AffinityTransactions data; eligibility.reasons[].code = affinity_device_coverage. |
| Mapping-key retention | 90 days after the latest dataset end date | Standard audiences only. MAID and IP mapping keys are retained for 90 days, so an older audience cannot be delivered as MAIDs or IPs: eligibility.notices[].code = audience_expired with blocks_identifiers = ["MAID", "IP"]. Other identifiers (EID, SCID, HEM) are unaffected; a MAID or IP pricing model is rejected with 422. |
| Web visitation lookback | 45 days | A WebDomain dataset’s start_date must fall within the 45-day window of available web data; an earlier date is rejected with 422. See Audiences. |
| Lookalike seed minimum | 1,000 devices | The completed seed audience must hold at least this many. |
| Lookalike output minimum to activate | 1,000 devices | A lookalike result audience must reach this before it can be activated. |
| Lookalike target size | 1 to 4,000,000 | The config.target_size range on a Lookalike Model create. |
| Estimate read wait | 1 to 15 seconds | The wait of Get Audience Estimate, counted from the moment the request arrives. The MCP estimate_audience_size tool waits up to about 12 seconds, get_audience_estimate up to 15. |
| Estimate calls waiting at once | 5 per organization, 25 in total | Reads with wait and the MCP estimate tools together, counted per organization and across all organizations. Another call answers at once, with the status the estimate has then. Only one call waits per estimate: a newer call for it takes the wait over. |
See Audiences.
Usage
| Limit | Value | Notes |
|---|---|---|
| Earliest reportable month | 2020-01 | GET /api/v2/usage rejects a yearmonth before this floor (or in the future). |
See Usage.
Pagination
per_page defaults and caps depend on the surface.
| Surface | Default per_page | Cap |
|---|---|---|
| Resource lists (audiences, activations, cohorts, projects, schedules) | 25 | 100 |
| Reference reads (Common, Web, CTV) | 500 | 500 |
| Apps reference reads | 250 | 500 |
On the reference reads, a larger per_page is read as the cap, and a
per_page that is zero, negative, or not a number as the default. The
pagination block reports the page size used.
On the paginated reference reads, a page above 10,000 is read as 10,000, and
a page below 1 or not a number as 1. Narrow a longer list with search or a
filter.