Audiences

Build audiences and Lookalike Models, and size an audience before building it. Conventions apply to every command here.

Create

Build an audience from one or two datasets of filters. See Create Audience.

Flags build a single dataset. Selector flags repeat for more than one value.

Built from flags, a create needs --type, --name, --start-date, and --end-date. Most types also require a --country, and the Body section of Create Audience lists the exceptions. The CLI checks for it before sending only on Origin, so for any other type a missing country is left to the API to reject.

Not every type reads --state, --city, and --zipcode. The location note under the Body section of Create Audience says which types do. The CLI sends them whatever the type, and the API rejects them on a type that does not read them.

--type is case-insensitive going in and canonical going out. It accepts the types listed under --type in intuizi audiences create --help. Get Dataset Types shows which types your account can build.

A type builds from flags when every field it requires has a flag. A type that requires a field no flag writes, such as cohort_id, profile_attributes, or the demographic filters, or that rejects the dates and signal providers the flags always send, goes through --file. --help names those types under --type, and the flags refuse them before anything is read or sent, --dry-run included: the command exits 2 with an error naming the missing field. Completion leaves them out of the --type values. The Body section of Create Audience gives each type’s required fields.

--category resolves against the catalog for the dataset type in use. For WebDomain that is the IAB categories, not the subcategories, and a name resolves to the number in the id column of intuizi reference web iab-categories, which is what Create Audience takes. An IAB code, which --quiet prints, resolves to its id too, even one that other codes contain: IAB1 is taken over IAB10 to IAB19, and an exact name such as Automotive works the same way. intuizi audiences create --help names the types it applies to, and any other type rejects it before anything is sent.

Omitting --provider includes every provider for the dataset type, which is almost always what you want. A --provider the type’s catalog does not list is rejected before anything is created. The CLI reads that catalog first, so the check needs a token. The API would accept such a provider and build an audience that completes with no devices. A --file body lists its own signal_providers.

--brand is POI only. Affinity brands travel in their own field, which no flag writes, so that filter needs --file.

--type origin filters on geography only. --country is required, and intuizi reference common countries --dataset-type Origin lists the countries with Origin data. --brand, --brand-all, and --category are rejected before anything is sent, and DMAs need --file. Origin data is weekly, so the API widens the window to the whole Monday-to-Sunday weeks it touches. The body keeps the dates as given, and stderr names the widened window when it differs.

intuizi audiences create \
  --type poi --brand "Example Coffee" \
  --country USA --state CA --city "San Francisco" \
  --start-date 2026-09-02 --end-date 2026-09-09 \
  --name "Coffee lovers - SF - 1 week" --wait

Any field no flag writes goes through --file, such as two datasets combined with an operator, the refine, crossvisitation, and cross purchase blocks, and POI locations and DMAs. See Create an Audience. No flag writes project_id either, so filing the audience under a project also goes through --file.

--frequency runs the frequency analysis for the dataset type as the audience builds: Visitation Frequency on POI, Apps Frequency on Apps, and Web Frequency on WebDomain. It sends the matching key of the analyses block, and any other type rejects it before anything is sent. The analysis counts the distinct days each device was seen, which activations preview sums and an activation’s --freq-min and --freq-max filter on. It cannot be added after the build, so an audience you may want to preview or filter by frequency needs it from the start. The frequency analyses require additional permissions which need to be approved by your Account Manager, and without them the create is refused with a 403.

The day-part variant of the analysis, and a frequency analysis on each dataset of a two-dataset audience, go in the analyses block of a --file body. A day-part audience cannot be previewed. The datastreams array, which asks for data stream visualizations, goes there too, and intuizi reference common datastream-visualizations --dataset-type <type> lists the ids it takes.

intuizi audiences create --file audience.json --wait

Waiting

--wait prints status changes on stderr and the last record read on stdout, whether the build completes, fails, runs past --timeout (default 60m), or gives up after three failed reads in a row. Only Completed exits 0, so branch on the exit code. With --json every outcome prints the API’s envelope, so the status is always .data[0].status.id. A wait that times out or gives up prints the envelope it last polled, and stderr names the intuizi audiences show <id> --wait that resumes it. See The Async Model.

The wait keeps polling through every status that means the build is still running: 100 to 103, 105 DataStreaming, 108 Modeling while a Lookalike Model trains, and 109 Visualizing data streams, which an audience that opts into data stream visualizations reports while it draws them, before 105 and Completed. Any other status ends the wait as a failure.

A timeout, or a wait that gives up, leaves the build running on the server, so resume it with intuizi audiences show <id> --wait rather than creating again. A failed build is final, so there is nothing to resume.

Status 107 Additional Info is one such failure. The build stopped because it cannot be built as defined, and its status will not change. The wait stops there, prints the record, and exits 1 without suggesting a resume. The API read carries only the status, not the reason. Audience Manager shows the reason on the audience, and the error on stderr points there. The usual cause is a date range outside the data loaded for its dataset, so fix the request and create the audience again.

Estimate create

Size an audience without creating it. See Estimate Audience Size.

audiences estimate create takes exactly what Create takes: the same flags, resolved the same way, and the same --file body. It sends the body to Estimate Audience Size, which runs the same build and reports how many devices the audience would hold. Nothing appears in Audience Manager, and no export, cohort, schedule, or activation follows. Swap estimate create for create in the same command line to build the audience that was estimated.

intuizi audiences estimate create \
  --type poi --brand "Example Coffee" \
  --country USA --state CA --city "San Francisco" \
  --start-date 2026-09-02 --end-date 2026-09-09 \
  --name "Coffee lovers - SF - 1 week" --wait

--frequency is there so the command line that builds the audience can be estimated unchanged. It needs the same permissions as on Create, but an estimate never runs an analysis, so it changes neither the figures nor the recipe_hash.

An estimate runs as long as a real build, scans the same data, and counts toward the monthly data-scan limit, as the estimate operation on intuizi usage, and toward the build budget. It comes back pending, with no figures, and its status then walks processing to one of completed, blocked, or failed.

The request carries an Idempotency-Key, as a create does. A retry after a 429 reuses it, and when an estimate gets no response at all, rerunning it with the --idempotency-key stderr printed returns the estimate the first attempt started, if it did, rather than scanning again (see Global flags).

recipe_hash is computed from the operator and datasets only, so the name does not change it. An audience created from the same body carries the same recipe_hash on intuizi audiences show <id> --json, which shows it is the audience that was estimated.

Estimate show

Read one size estimate by id. See Get Audience Estimate.

Takes the id estimate create returned.

A completed estimate leads with its figures: uniques, the approximate distinct device count, with a standard error of about 2.3%, then visits, signals, and unique_eips where the dataset types produce them, and as_of. The rest of the estimate object, such as providers and method, follows as rows of its own. A blocked estimate shows its code and reason as blocked, such as OUT_OF_COVERAGE with the dates the data covers, and a failed one explains itself in status_message. --json prints the record as the API returns it, with the figures under .data[0].estimate.

An estimate’s status is a word, not a status id. With --wait, pending and processing keep the wait going, and completed exits 0. blocked and failed are final: the wait stops there, prints the record, and exits 1 with the reason on stderr, naming no command to resume it. So does a status the CLI does not know. A timeout, or a wait that gives up after three failed reads in a row, leaves the estimate running on the server, and stderr names the intuizi audiences estimate show <id> --wait that resumes it.

intuizi audiences estimate show <id> --wait
intuizi audiences estimate show <id> --json | jq '.data[0].estimate.uniques'

List

Page through the audiences in your account. See List Audiences.

Show

Read one audience by id. See Get Audience.

The wait reads each status as Waiting describes, including 107 and 109, and this is the command that resumes a wait that timed out or gave up.

normalized_payload is the canonical copy of the name, operator, and datasets the audience was created from. The recipe_hash field next to it (.data[0].recipe_hash, not inside normalized_payload) is computed from the operator and datasets only, not the name. Top-level blocks such as crossvisitation, crosspurchase, and analyses are not part of normalized_payload. It is set only on audiences built through Create Audience, which is what audiences create calls. It is null for Lookalike Models, for the audiences a schedule builds each cycle, for audiences built in Audience Manager, and for audiences created before the field existed:

intuizi audiences show <id> --json | jq '.data[0].normalized_payload'

Delete

Remove one audience. This cannot be undone. See Delete Audience.

A cohort created from a regular audience with cohorts create --audience-id is deleted with it. Cohorts created from a Lookalike Model are not. Deleting a Lookalike Model that is still modeling stops the run. Data an activation already delivered stays where it was delivered.

Lookalike create

Train a model on a completed audience and produce a new one. See Create Lookalike Audience.

Lookalike Models require additional permissions which need to be approved by your Account Manager. That applies to lookalike cancel too. The seed must be completed, must not itself be a lookalike, and must meet the minimum device count in Limits & Quotas.

Built from flags, a Lookalike Model needs --name, --source-audience-id, --target-size, at least one --signal, and at least one --country.

A Lookalike Model draws its candidates from Origin data, which covers only some countries, and the create accepts any country code. A run whose countries have no Origin data fails after it is created, and when only some of them do, the others are left out of the model without an error. Pick the countries from intuizi reference common countries --dataset-type Origin.

The accepted --signal values are on Create Lookalike Audience.

--notify is always sent, so the completion email goes out unless --notify=false is given. A --file body sets notification itself, and the email goes out when it is left out.

intuizi audiences lookalike create \
  --name "Coffee lovers lookalike" --source-audience-id <id> \
  --target-size 500000 --signal poi --signal apps --country USA

lookalike create has no --wait. Training shows as status 108 Modeling, which is not terminal, and intuizi audiences show <id> --wait follows the new audience through it to Completed. See Build a Lookalike Model.

Lookalike cancel

Stop a model run at its next checkpoint. See Cancel Lookalike.

Takes the id lookalike create returned, not the seed’s --source-audience-id:

intuizi audiences lookalike cancel <id>

The run stops at its next checkpoint. Until then the audience reads 108 Modeling, and once the run stops it ends at 400 Error, which is final and never reaches Completed. intuizi audiences show <id> --wait follows a cancelled run to that status and exits 1, as it does for any failed build. A cancel that arrives once the result is already being published is ignored, and the run completes. A run that has already finished cannot be cancelled. To remove a cancelled run from your lists, run intuizi audiences delete <id>. The confirmation on stderr still says the run keeps reading 108 Modeling and not to --wait on it. That note predates the 400 ending, and the intuizi audiences delete <id> it names still removes the run.