Skip to content
How to use
Build a Lookalike Model
.md

Build a Lookalike Model

A Lookalike Model learns the behavior of a completed seed audience and produces a new audience of similar devices at the size you ask for. This guide runs the full journey: pick a seed, create the model, poll it to Completed, then activate the result. Every field value comes from an endpoint - fetch it there rather than guessing.

Lookalike Models are a gated feature. They require additional permissions which need to be approved by your Account Manager. Without the capability the create is rejected with 403.

The journey 

1. List audiences          -> choose a Completed, non-lookalike seed (1,000+ devices)
2. POST .../create-lookalike -> 201, returns the new result-audience id
3. GET  .../audiences/{id}   -> poll 108 Modeling until 104 Completed
4. Activate the result       -> deliver it (1,000-device floor for lookalikes)

Each step is asynchronous - see The Async Model.

Prerequisites

  • A bearer token (Authentication).
  • The Lookalike Models capability enabled on your account (see the note above).
  • A seed audience that is already Completed.

Step 1 - Pick a seed audience

The seed is any completed audience your company owns. List your audiences and choose one that satisfies all three seed rules:

  • lifecycle status 104 Completed (status.id),
  • not itself a lookalike (is_lookalike is false), and
  • at least 1,000 devices (results_count >= 1000) by default.
curl "https://console.intuizi.com/api/v2/analyses/audiences/index?per_page=25" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Accept: application/json"

Each item in the response carries status, is_lookalike, and results_count so you can screen candidates directly. The full read is documented at List Audiences; to inspect one candidate in detail see Read an Audience.

Step 2 - Create the Lookalike Model

Point the create at your seed’s id and supply the model config. The complete, field-level contract - target_size, the geo scope, the signals families the model learns from (poi, apps, demographics, transactions, profile_attributes; web and ctv are withdrawn), seed-device exclusion, an optional contrast audience, and identifier expansion - is on Create Lookalike Audience. Fetch any catalog values (for example the geo.countries) from the reference reads under Working with Reference Data rather than hardcoding them.

curl -X POST "https://console.intuizi.com/api/v2/analyses/audiences/create-lookalike" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: <UNIQUE_KEY>" \
  -d '{
    "name": "Coffee Buyers - Lookalike",
    "source_audience_id": 88,
    "config": {
      "target_size": 100000,
      "geo": { "countries": ["USA"], "states": [] },
      "signals": ["poi", "apps", "demographics"],
      "exclude_seed_devices": true,
      "contrast_audience_id": null,
      "expand_eids": false
    }
  }'

The response returns the new result audience in status 100 Initiating with is_lookalike: true. Capture its id - that is what you poll.

The Idempotency-Key header is optional and you generate it yourself, one per logical create. Reuse it only when retrying the exact same request: the retry replays the original response instead of launching a second model run. See Idempotency.

Step 3 - Poll until Completed

Poll the result audience by id until it finishes. A Lookalike Model spends its working time in status 108 Modeling; keep polling until it reaches 104 Completed.

curl "https://console.intuizi.com/api/v2/analyses/audiences/<LOOKALIKE_ID>" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Accept: application/json"
  • 100-103, 105, 108 Modeling, 109 - still working. Poll again shortly.
  • 104 Completed - the lookalike audience is ready.
  • 107 Additional Info - the build stopped and will not continue. Stop polling. Audience Manager shows the reason on the audience.
  • 4xx - an error state, including the 400 a run you cancel ends at (see Cancel an in-flight run). Stop polling and inspect the response.

See Polling and Rate Limits for recommended intervals and how to handle a 429.

Step 4 - Activate the result

A completed lookalike audience activates exactly like any other audience - see Activate an Audience for the full flow.

Lookalike audiences carry a higher activation floor: a lookalike must hold at least 1,000 unique devices to be activated (ordinary audiences activate from 500) - one of several gates the eligibility engine checks (device floor, Affinity SCID coverage, retention). The audience read’s is_activation_allowed boolean reflects the combined verdict, and eligibility.reasons[] names the specific gate when it is false - check it before you activate.

Cancel an in-flight run

If you no longer need a model that is still running, request cancellation. This is cooperative: the run stops at its next checkpoint rather than being killed instantly, and a run that has already finished cannot be cancelled. Until that checkpoint the audience keeps reading 108 Modeling. Once the run stops it ends at 400 Error, which is final, and an audience.failed webhook is sent. Audience Manager shows the status as Cancelled on request. A cancel that arrives once the result is already being published is ignored, and the run completes at 104.

curl -X POST "https://console.intuizi.com/api/v2/analyses/audiences/cancel-lookalike" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "id": <LOOKALIKE_ID> }'

The full contract is at Cancel Lookalike.

Reference

List, Get & DeleteCloud Cohort to Activation