The Async Model

Creating an audience or an activation does not finish the work in the request. The Intuizi API uses a create-then-poll model: the write endpoint validates your input, persists the resource, and hands the heavy processing to a background worker. You get an immediate response with an id, then you poll the resource by id until its lifecycle status says it is done.

Why async

Resolving an audience’s filters into a population, counting devices, and streaming an activation to a partner all take longer than a single HTTP request should hold open. So the create call returns fast, and the actual work happens out of band.

The pattern

1. POST .../create          -> 201, returns the new resource id + initial status
2. GET  .../{id}            -> read the lifecycle status
3. repeat step 2            -> until status is 104 Completed
4. act on the result

A 201 Created on the create, or a 200 OK on the read, only means “the request succeeded”. It does not mean the audience or activation is ready. Always check the lifecycle status id inside data - see Status Codes.

Lifecycle status ids

The lifecycle status is a separate field from the HTTP code (these ids come from the platform’s ActivationDefines):

Terminal states

• Audience: poll until 104 Completed before activating it.
• Activation: poll until 104 Completed, then read datastreams[].results.uri. 105 DataStreaming happens before 104 (the ids are not sequential - the delivery step was added later and took the next free id). At 105 results are still being delivered.
• Failure: 104 Completed is the only success. A build that stops at 107 Additional Info or at a 4xx error state has failed and never changes again, and neither does a resource at 106 Expired.

Size estimates can wait for the answer

A size estimate has a lifecycle of its own: status is pending or processing until it ends at completed, blocked, or failed. The create answers at once, like every create. The read takes wait, so one request can wait for the answer instead of a poll loop:

1. POST .../audiences/estimate                -> 201, the estimate id, status "pending"
2. GET  .../audiences/estimate/{id}?wait=15   -> answers as soon as the estimate is done,
                                                 at the latest 15 seconds after the request
3. repeat step 2                              -> while status is still pending or processing

At most 5 calls of an organization, and 25 across all organizations, wait at once. Only one call waits per estimate: a newer call for the same estimate takes the wait over, and the older one answers at once. A call that cannot wait answers at once with the status as it is, so a read that answers pending well before its wait has passed could not wait: pause before the next read, as you would between polls (for example 5 seconds).

The MCP tools do this for the agent, within the same limits: estimate_audience_size waits up to about 12 seconds for the answer, and get_audience_estimate up to 15 seconds. See Get Audience Estimate.

Push instead of poll

Polling is the fallback, not the recommended integration for long-running work. Register a webhook in the console (My Organization > Webhooks) and Intuizi POSTs a signed notification to your server the moment an audience, activation or cohort completes or fails - carrying the same object the GET read returns, so no follow-up call is needed. This removes the wasted request budget and the discovery latency of polling, and it matters most for the slow builds (lookalike models, large activations).

The lifecycle is unchanged: webhooks fire on 104 Completed and on the failures, 107 Additional Info and the 4xx error states (the 400 a cancelled Lookalike Model ends at included), and on a cohort’s 4 Completed and 5 Not Available. 105 DataStreaming still happens before 104 - there is no webhook for it, exactly as you would keep polling through it. Keep a low-frequency poll or an on-demand GET as the fallback for a delivery that exhausts its retries: the resource read is always the source of truth.

Polling guidance

• Poll on an interval (for example every few seconds), not in a tight loop.
• Treat 100-103, 105, 108 (Modeling), and 109 (Visualizing data streams) as “keep waiting”.
• Treat 107 (Additional Info) as a stopped build and stop polling. It does not resume. Read the reason in Audience Manager, change the request (for example, a date range the dataset has data for), and create it again.
• Treat 106 (Expired) as final: the resource has aged out.
• Treat any 4xx lifecycle id as an error state and stop polling.
• Build a sensible timeout into your client.

See Audiences vs Activations for how the two resources chain together.