Polling & Rate Limits

Most write operations on the Intuizi API are asynchronous, so a well-behaved client spends most of its time doing two things: polling a resource until it is ready, and staying inside the rate limits while it does. This guide covers both, plus how to retry safely. It applies equally whether you are writing an integration by hand or driving the API from an AI agent - the same intervals, limits, and retry rules keep an autonomous loop from hammering the API or double-creating resources.

The two rate buckets

Limits are enforced per token (an agent’s MCP token counts the same as an API bearer token):

Polling counts against the read bucket, so a tight poll loop can exhaust 120 reads/min on its own. Space your polls out (below) and you will stay well under it.

The build budget

Rate buckets are per token and per minute. Separately, every create that starts a worker job (an audience, an estimate, a Lookalike Model, a cohort, an activation) counts against your organization’s build budget: 60 per rolling hour and 300 per rolling day by default, shared across every token, MCP and the console. Over the budget you get the same 429 + Retry-After as a rate bucket, and nothing is created. GET /api/v2/usage reports the budget and your live counts under build_budget - check it before a batch and pace the batch to it instead of retrying on 429. Scheduled replays never count.

How to poll

Creating an audience, activation, cohort, or Lookalike Model returns immediately with an id; the work finishes in the background (see The Async Model). Poll the matching GET .../{id} endpoint and read the lifecycle status inside data:

• 100-103, 108 (Modeling), and 109 (Visualizing data streams) - still working. Keep polling.
• 105 (DataStreaming) - an activation is delivering to the destination; keep polling. Note 105 happens before 104.
• 104 (Completed) - the only terminal success state; stop polling and act on the result.
• 107 (Additional Info) - the build or export stopped and will not continue. Stop polling. Audience Manager shows the reason. Fix the request and create it again.
• 4xx lifecycle ids - an error state. Stop polling and inspect the resource.

Recommended approach:

• Poll on an interval of a few seconds to start, and back off as the wait grows (for example 5s, then 10s, then 30s). Do not poll in a tight loop.
• Build a sensible overall timeout into your client so a stuck job does not poll forever.
• Only the lifecycle status tells you the work is done - a 200 OK on the read just means “here is the current state”. See Status Codes.

Handling a 429

If you exceed a bucket you get 429 Too Many Requests. The response carries a Retry-After value (seconds to wait); the same value also appears in the error text. Do not retry immediately.

1. Read Retry-After from the 429 response.
2. Wait that many seconds.
3. Retry the request.

A backoff-and-retry-on-429 wrapper around your HTTP client is the simplest way to stay compliant without hand-tuning every call. See Errors for the 429 envelope.

Retrying a create safely

A 429 or a 5xx on a create is the risky case: you do not know whether the resource was made. Make creates idempotent so a retry can never double-create:

• Generate an Idempotency-Key (a UUID) before the first attempt.
• On any retry of that same create, resend the same key. If the original request had actually succeeded, you get its response back (Idempotency-Replayed: true) instead of a duplicate; if it never ran, the retry executes cleanly.

Full semantics - including which eight endpoints honor the header - are on Idempotency.

Notes for AI agents

• Tool calls over MCP consume the same per-token buckets as direct API calls (120 reads/min, 30 writes/min, plus 120 MCP requests/min). A polling loop is read traffic.
• On a 429, the tool error text includes the Retry-After seconds - wait, then retry, rather than looping immediately.
• The create tools accept an idempotency_key argument - set it once per logical create and reuse it across retries so an interrupted run never doubles up.
• The full agent journey, from connecting a client to a delivered audience, is Automate with an AI Agent.

Reference

• The Async Model
• Status Codes
• Idempotency
• Errors