# Audiences


Build audiences and Lookalike Models, and size an audience before building
it. [Conventions](/cli/reference#conventions) apply to every command here.

## Create

Build an audience from one or two datasets of filters.
See [Create Audience](/api/v2/audiences#post-apiv2analysesaudiencescreate).

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

| Flag | Input | Lookup |
| --- | --- | --- |
| `--type` | dataset type, case-insensitive | `intuizi audiences create --help` |
| `--name` | any string | |
| `--start-date` `--end-date` | `YYYY-MM-DD` | |
| `--brand` | name or id, POI only | `reference poi brands` |
| `--brand-all` | a search, taking every match (POI only) | same |
| `--category` | name or id, for the types named in `--help` | the catalog for the dataset type |
| `--provider` | id. Defaults to every provider for the type | `reference common signal-providers --data-type <type>` |
| `--country` | ISO-3 code | `reference common countries --dataset-type <type>` |
| `--state` | state code | `reference common states --countries <code>` |
| `--city` | city name | `reference common cities --states <code>` |
| `--zipcode` | zip code | `reference common zipcodes --cities <name>` |
| `--frequency` | run the frequency analysis for the dataset type: POI, Apps, or WebDomain | |
| `--file` | the whole body as JSON, or `-` for stdin, forwarded untouched | |
| `--dry-run` | print the body and create nothing. It still resolves names and reads the signal-provider catalog, so it needs a token | |
| `--wait` `--timeout` | poll until the build completes or fails, then print the last record read. See [Waiting](/cli/reference/audiences#waiting) below | |

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](/api/v2/audiences#post-apiv2analysesaudiencescreate) 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](/api/v2/audiences#post-apiv2analysesaudiencescreate) 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](/api/v2/common#get-apiv2analysesreferencecommondataset-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](/api/v2/audiences#post-apiv2analysesaudiencescreate) 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.

```bash
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](/guides/create-an-audience).
No flag writes `project_id` either, so filing the audience under a
[project](/cli/reference/projects) 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`](/api/v2/audiences#frequency-analysis) block, and any other type
rejects it before anything is sent. The analysis counts the distinct days each
device was seen, which
[`activations preview`](/cli/reference/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`](/api/v2/audiences#datastream-visualizations) array, which asks
for data stream visualizations, goes there too, and
`intuizi reference common datastream-visualizations --dataset-type <type>`
lists the ids it takes.

```bash
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](/concepts/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](/api/v2/audiences#datastream-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](/api/v2/audiences#post-apiv2analysesaudiencesestimate).

`audiences estimate create` takes exactly what [Create](#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.

| Flag | Input | Lookup |
| --- | --- | --- |
| `--type` `--name` `--start-date` `--end-date` `--brand` `--brand-all` `--category` `--provider` `--country` `--state` `--city` `--zipcode` | as on [Create](#create) | as on [Create](#create) |
| `--frequency` | accepted and checked as on [Create](#create), but an estimate never runs the analysis | |
| `--file` | the whole body as JSON, or `-` for stdin, forwarded untouched | |
| `--dry-run` | print the body and send nothing. It still resolves names and reads the signal-provider catalog, so it needs a token | |
| `--wait` `--timeout` | poll until the estimate is completed, blocked, or failed, then print the last record read. See [Estimate show](#estimate-show) | |

```bash
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`](/cli/reference/usage), and toward the
[build budget](/concepts/limits#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](/cli/reference#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](/api/v2/audiences#get-apiv2analysesaudiencesestimateid).

Takes the id `estimate create` returned.

| Flag | Input |
| --- | --- |
| `--wait` `--timeout` | poll until the estimate is completed, blocked, or failed, then print the last record read |

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.

```bash
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](/api/v2/audiences#get-apiv2analysesaudiencesindex).

| Flag | Input |
| --- | --- |
| `--search` | contains match on the audience name |
| `--page` `--per-page` | page through the results |

## Show

Read one audience by id.
See [Get Audience](/api/v2/audiences#get-apiv2analysesaudiencesid).

| Flag | Input |
| --- | --- |
| `--wait` `--timeout` | poll until the build completes or fails, then print the last record read |

The wait reads each status as [Waiting](/cli/reference/audiences#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:

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

## Delete

Remove one audience. This cannot be undone.
See [Delete Audience](/api/v2/audiences#post-apiv2analysesaudiencesdelete-by-id).

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.

| Flag | Input |
| --- | --- |
| `--yes` | skip the confirmation prompt. Required when stdin is not a terminal |

## Lookalike create

Train a model on a completed audience and produce a new one.
See [Create Lookalike Audience](/api/v2/audiences#post-apiv2analysesaudiencescreate-lookalike).

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](/concepts/limits).

| Flag | Input | Lookup |
| --- | --- | --- |
| `--name` | any string | |
| `--source-audience-id` | the seed audience | `audiences list` |
| `--target-size` | device count for the result | [Limits & Quotas](/concepts/limits) |
| `--signal` | data family to learn from, repeatable | |
| `--country` | ISO-3 code, repeatable | `reference common countries --dataset-type Origin` |
| `--state` | state code, repeatable | `reference common states --countries <code>` |
| `--exclude-seed-devices` | leave the seed's devices out of the result | |
| `--expand-eids` | expand matched devices to their EIDs | |
| `--contrast-audience-id` | a completed, non-lookalike audience other than the seed. The seed's own id is refused before anything is sent (exit `2`) | `audiences list` |
| `--notify` | email the user who created the run when it completes. On by default, and `--notify=false` turns it off | |
| `--file` | the whole body as JSON, or `-` for stdin, forwarded untouched | |
| `--dry-run` | print the body, create nothing | |

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](/api/v2/audiences#post-apiv2analysesaudiencescreate-lookalike).

`--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.

```bash
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](/guides/build-a-lookalike-model).

## Lookalike cancel

Stop a model run at its next checkpoint.
See [Cancel Lookalike](/api/v2/audiences#post-apiv2analysesaudiencescancel-lookalike).

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

```bash
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.

{{< cards >}}
  {{< card link="/developers/cli/reference/auth/" title="Auth" subtitle="Log in and out." >}}
  {{< card link="/developers/cli/reference/activations/" title="Activations" subtitle="Deliver an audience to an endpoint connection." >}}
{{< /cards >}}