# Activations


Deliver a completed audience to an endpoint connection, and preview the
devices a frequency filter would deliver.
[Conventions](/cli/reference#conventions) apply to every command here.

## Create

Export a completed audience to an endpoint connection.
See [Create Activation](/api/v2/activations#post-apiv2analysesactivationscreate).

The audience must be completed and eligible for activation: it must meet the
activation minimum in [Limits & Quotas](/concepts/limits) and pass the other
eligibility checks. The audience read reports the audience-level verdict up
front in `is_activation_allowed`, and when that is `false`,
`eligibility.reasons` says why. A `true` can still carry
`eligibility.notices`. A notice does not block on its own: it names the
identifiers it blocks in `blocks_identifiers`, and an activation whose pricing
model delivers one of them is refused. See [Limits & Quotas](/concepts/limits)
for the rules behind each notice.

```bash
intuizi audiences show <id> --json | jq '.data[0] | {is_activation_allowed, reasons: .eligibility.reasons, notices: .eligibility.notices}'
```

| Flag | Input | Lookup |
| --- | --- | --- |
| `--audience-id` | the audience to export | `audiences list` |
| `--endpoint-connection-id` | the destination | `reference common endpoint-connections` |
| `--pricing-model-id` | a pricing model of the connection's partner | `reference common pricing-models --partner-id <partner_id>` |
| `--datastream` | a datastream of the connection's partner to deliver, repeatable or comma-separated | `reference common datastreams --partner-id <partner_id>` |
| `--description` | a label for the activation | |
| `--project-id` | the project to file it under. Left out, the activation takes the audience's project | `projects list` |
| `--freq-min` `--freq-max` | deliver only the devices seen on this range of distinct days, both inclusive. Both or neither | `activations preview` |
| `--filter-hash` | the `filter_hash` a preview printed for the same range | `activations preview` |
| `--file` | the whole body as JSON, or `-` for stdin. Not combined with the flags above | |
| `--dry-run` | print the body, create nothing | |
| `--wait` `--timeout` | poll until it completes or fails. `--timeout` defaults to 60m | |

Built from flags, an activation needs `--audience-id`,
`--endpoint-connection-id`, and `--pricing-model-id`.

Pricing models and datastreams are read per partner, and the partner is the
connection's own: `partner.id` on the connection. The table shows the nested
partner as `{...}`, so read it with `--json`:

```bash
intuizi reference common endpoint-connections --json | jq '.data[] | {id, name, partner_id: .partner.id, inputs: .partner.inputs}'
intuizi reference common pricing-models --partner-id <partner_id>
intuizi reference common datastreams --partner-id <partner_id>
```

A pricing model from any other partner is rejected. Each datastream lists the
dataset types it applies to in its `dataset_types` column, and a stream that
applies to none of the audience's is rejected. A Lookalike Model counts as
`cohorts` here, whatever its seed was built from, so pick streams whose
`dataset_types` include `cohorts`.

An activation delivers only through the datastreams it enables. Copy each
`--datastream` id from
`reference common datastreams --partner-id <partner_id>`. The server drops an
id it does not know, or a private stream your account is not assigned, without
an error, and the create still succeeds. That list does not mark which streams
are private, and it can include private ones your account is not assigned.
Once the activation completes, list its delivery results:

```bash
intuizi activations show <id> --json | jq '.data[0].datastreams[] | {name, status}'
```

Each result is named by the stream's internal slug, not by the name that
`reference common datastreams` prints (`affinity_transactions_summary` for
Transactions Summary, for example), so compare counts rather than names. Fewer
results than distinct streams you enabled means one was dropped: check its id,
and if the id is right, ask your Account Manager to assign the stream to your
account. A Deidentified audience always reports a single `deidentified`
result, whatever streams were enabled, so this check does not apply to it.

Without any datastream, the activation still runs to Completed but delivers
nothing, so the command warns on stderr, with `--dry-run` too.

```bash
intuizi activations create \
  --audience-id <id> \
  --endpoint-connection-id <connection_id> \
  --pricing-model-id <pricing_model_id> \
  --datastream <datastream_id> --wait
```

The flags above cover a partner that takes no account inputs, whose data lands
at the partner's own destination. When the connection's `partner.inputs` lists
an input, such as a bucket name or folder prefix that sets where the data
lands, send its value in a fuller body: the API does not fill it from the
values saved on the connection. Partner inputs, per-stream inputs and
compression, and caller-supplied credentials all travel in that fuller body,
which goes through `--file`. A `default_value` passes the
API's check for a required input but is not copied into the delivery, so send
the value itself. See
[Deliver to a Partner Endpoint](/guides/deliver-to-a-partner-endpoint).

`--freq-min` and `--freq-max` deliver only the devices seen on that range of
distinct days in the audience's date window. The audience must have been built
with a frequency analysis, as `audiences create --frequency` builds it (see
[Audiences](/cli/reference/audiences#create)). The range is sent with
`freq_limit: true`, which the API requires beside any bound. Count the range
first with [Preview](#preview), and pass the `filter_hash` it printed as
`--filter-hash`. The API recomputes the hash from the audience as it is stored
at create time, so an activation whose range differs from the preview, or
whose audience was rebuilt since, is refused with a `422` rather than
delivering something else. A lone bound, a hash without its range, and a
negative or upside-down range are refused before anything is sent. The
activation read echoes the filter as `filters` and the hash as `filter_hash`.

```bash
intuizi activations create \
  --audience-id <id> \
  --endpoint-connection-id <connection_id> \
  --pricing-model-id <pricing_model_id> \
  --datastream <datastream_id> \
  --freq-min 2 --freq-max 5 --filter-hash <filter_hash> --wait
```

With `--wait`, each status change goes to stderr and the record the wait ended
on to stdout. The wait polls through `100` to `103`, `105` DataStreaming,
`108` Modeling, and `109` Visualizing data streams, the statuses that mean the
work is still in progress, and exits `0` at Completed (`104`). It exits `1`
when the activation reaches any other status, `107` Additional Info included,
when it reaches Completed with a datastream result that carries an `error` (its
`status` reads `failed`, or `skipped` when the stream cannot run on this
audience's data), when `--timeout` runs out, or when three reads in a row
fail, and it still prints the last record it read. A Completed activation with no datastreams exits `0`, and stderr notes
that nothing was delivered. See [Status Codes](/concepts/status-codes) for the
lifecycle.

A timeout, or a wait that gives up, leaves the activation running on the
server, so resume it with `intuizi activations show <id> --wait` rather than
creating again. A failed activation is final, so there is nothing to resume.
Status `107` Additional Info is one such failure: the export stopped because it
cannot be processed as requested, and its status will not change. The wait
stops there, prints the record, and exits `1`, and the error names no command
to resume it. The API read carries only the status, not the reason, and
Audience Manager shows the reason on the activation. Fix what it names and
create a new activation.

## Preview

Count the devices a frequency filter would deliver, before creating the
activation.
See [Preview Activation](/api/v2/activations#get-apiv2analysesactivationspreview).

| Flag | Input | Lookup |
| --- | --- | --- |
| `--audience-id` | a Completed audience built with a frequency analysis | `audiences list` |
| `--freq-min` | fewest distinct days a device was seen, inclusive | `frequency_bounds` of an earlier preview |
| `--freq-max` | most distinct days a device was seen, inclusive. The upper bound of `frequency_bounds` makes an open-ended range | `frequency_bounds` of an earlier preview |

All three are required. A read-only dry run of the filter
`activations create --freq-min --freq-max` applies: nothing is created,
delivered, or billed, so preview as many ranges as you like.

```bash
intuizi activations preview --audience-id <id> --freq-min 2 --freq-max 5
```

After the audience's name, the output leads with `filtered_count`, the exact
number of devices seen on `--freq-min` to `--freq-max` distinct days in the
audience's date window. It is the count Audience Manager shows as Limit
Audience for the same Freq. Range. Next come the range as `freq_range`, the `frequency_bounds` a range
must fall inside, the audience's `source_count` and `histogram_total`, and the
`filter_hash` to pass to `activations create --filter-hash`. Under them, a
table lists the whole histogram: the number of devices seen on each number of
distinct days, the buckets a range sums. `source_count` is the audience total,
an approximate count, and `histogram_total` is the exact sum of the histogram,
so the two can differ slightly. `--json` prints the response as the API
returns it, with the `limitations` that explain each count. `--quiet` is
refused: a preview returns a count, not an id.

The audience must be Completed and built with exactly one frequency analysis:
`audiences create --frequency`, or the matching `analyses` key in a `--file`
body. The API refuses any other audience with a `422` that says why, such as
an audience built without the analysis, a day-part analysis, a Lookalike
Model, or a cohort. A range outside `frequency_bounds` is a `422` that names
the bound. The CLI refuses a negative or upside-down range before anything is
sent.

To deliver exactly what was previewed, pass the same range and the
`filter_hash` to [Create](#create):

```bash
hash=$(intuizi activations preview --audience-id <id> --freq-min 2 --freq-max 5 \
  --json | jq -r '.data[0].filter_hash')
```

## List

Page through the activations in your account.
See [List Activations](/api/v2/activations#get-apiv2analysesactivationsindex).

| Flag | Input |
| --- | --- |
| `--search` | contains match on the activation description |
| `--page` `--per-page` | page through the results |

## Show

Read one activation by id.
See [Get Activation](/api/v2/activations#get-apiv2analysesactivationsid).

The table shows the lifecycle status and counts the datastream results. These
are the activation's delivery results, not the streams the create enabled, and
they appear only once the activation is Completed (`104`). Until then,
including right after a create that enabled streams, the count reads
`[0 items]`. Each result's `status`, delivered file (`results.uri`), and
`error` are in `--json`:

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

| Flag | Input |
| --- | --- |
| `--wait` `--timeout` | poll until it completes or fails, as on create. A Completed activation returns at once, and this is the command that resumes a wait that timed out or gave up |

## Delete

Remove one activation. Delivered data is unaffected.
See [Delete Activation](/api/v2/activations#post-apiv2analysesactivationsdelete-by-id).

| Flag | Input |
| --- | --- |
| `--yes` | skip the confirmation prompt |

{{< cards >}}
  {{< card link="/developers/cli/reference/audiences/" title="Audiences" subtitle="Build audiences and Lookalike Models." >}}
  {{< card link="/developers/cli/reference/cohorts/" title="Cohorts" subtitle="Import your own identifiers." >}}
{{< /cards >}}