Activations

Deliver a completed audience to an endpoint connection, and preview the devices a frequency filter would deliver. Conventions apply to every command here.

Create

Export a completed audience to an endpoint connection. See Create Activation.

The audience must be completed and eligible for activation: it must meet the activation minimum in Limits & Quotas 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 for the rules behind each notice.

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

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:

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:

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.

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.

--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). The range is sent with freq_limit: true, which the API requires beside any bound. Count the range first with 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.

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

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.

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:

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.

Show

Read one activation by id. See Get Activation.

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:

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

Delete

Remove one activation. Delivered data is unaffected. See Delete Activation.