Activations

Activate (export) a completed audience to an endpoint connection, then list, read and delete activations - and preview the frequency filter an activation would apply before you create it. Activation is asynchronous: the create call returns immediately with a new id, and you poll the get endpoint until its datastreams report their output.

All activation endpoints are authenticated and JSON-only. Send Authorization: Bearer <token> and Accept: application/json on every call (plus Content-Type: application/json on the POST create). Reads use the read rate bucket (120 requests/min per caller); create and delete use the write bucket (30 requests/min per caller).

Create Activation

POST /api/v2/analyses/activations/create

Creates an activation that exports a custom audience owned by your company to a company-scoped endpoint connection. The audience must be 104 Completed and hold at least 500 unique devices - the audience read’s is_activation_allowed field tells you eligibility up front. When it is false, eligibility.reasons[0].message tells you why (device floor, Affinity device coverage, retention) and the activation endpoint returns 422 with the same message. The export is queued asynchronously; poll GET /api/v2/analyses/activations/{id} for its status and datastream output.

Auth: bearer token + Accept: application/json + Content-Type: application/json. Rate limit: write bucket (30 requests/min). Optional: Idempotency-Key header (see below).

Body

Field	Type	Required	Description
`audience_id`	integer	Yes	The audience to export. Must be owned by your company.
`endpoint_connection_id`	integer	Yes	The destination endpoint connection. Must be owned by your company. Resolves the partner, pricing and datastreams server-side.
`pricing_model_id`	integer	Yes	The pricing model id for the activation.
`description`	string	No	A label for the activation (max 255 chars).
`project_id`	integer	No	A project id owned by your company to file the activation under.
`credentials`	object	No	Caller-supplied destination credentials (see the credentials note). Write-only and sensitive.
`audience_inputs`	array	Per partner definitions	Partner account-detail values, index-matched to the connection’s `partner.inputs` definitions from Get Endpoint Connections. Inputs flagged `required` must be supplied for every enabled datastream (here or per stream).
`datastreams`	object[]	No	The partner outputs to enable. Each entry is `{ id, status, compression, inputs, service_account, visualizing_status }`.
`datastreams[].inputs`	array	Per partner definitions	Per-stream partner input values, index-matched to `partner.inputs` exactly like `audience_inputs` (per-stream values win).
`datastreams[].service_account`	object	No	The decoded service-account JSON key. Only accepted when the partner defines a `file`-type input (GCP-style destinations); otherwise rejected. Write-only and sensitive.
`datastreams[].visualizing_status`	boolean	No	Whether this stream also feeds visualization.
`datastreams[].id`	integer	Required with `datastreams`	The datastream id (re-resolved server-side through your company’s permitted set). An enabled stream must apply to the audience’s dataset types - each item of Get Datastreams lists its `dataset_types`, and a lookalike audience counts as `cohorts`. A mismatch is a `422` naming the stream; it is not silently dropped, because a stream run against the wrong dataset produces a broken file rather than an empty one.
`datastreams[].status`	boolean	No	Whether to enable this datastream.
`datastreams[].compression`	string	No	Compression for this datastream.
`freq_limit`	boolean	With `freq_min` / `freq_max`	Enable the frequency filter. The export applies `freq_min` / `freq_max` only when this is `true`, so bounds sent without an explicit `freq_limit` are rejected - a filter is never applied implicitly. Must be `true` when `filter_hash` is sent.
`freq_min`	integer	With `filter_hash`	Lowest distinct visit-day count to export (inclusive). Preview the resulting count first with Preview Activation.
`freq_max`	integer	With `filter_hash`	Highest distinct visit-day count to export (inclusive).
`filter_hash`	string	No	The `filter_hash` returned by Preview Activation for the same `audience_id`, `freq_min` and `freq_max`. Recomputed server-side from the audience as stored now; a different range, or an audience rebuilt since the preview, is rejected - so the export applies exactly what was previewed. Echoed on the activation read.
`limit`	integer	No	Result cap.
`distance_limit`	boolean	No	Enable the distance limit.
`distance`	number	No	Distance value.
`compression`	string	No	Top-level compression.
`price`	number	No	Price override.
`notification`	boolean	No	Whether to notify on completion.

partner_id, partner_name and pricing_model are prohibited in the body. The partner, pricing and datastreams are always derived server-side from the company-scoped endpoint_connection_id. Sending any of these prohibited fields is rejected with 422.

Caller-supplied credentials

credentials is an optional, write-only and sensitive map of string keys to simple values (strings, numbers or booleans). It is never logged, never echoed, and never returned in any response.

When present, the caller-supplied credentials override the endpoint connection’s stored credentials for this export.
When absent, the server falls back to the connection’s stored, server-decrypted credentials.
If the connection has no stored credentials and the caller supplies none, the activation is rejected with 422 (there is nothing to authenticate the export with).

curl -X POST "https://console.intuizi.com/api/v2/analyses/activations/create" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: <UNIQUE_KEY>" \
  -d '{
    "audience_id": 88,
    "endpoint_connection_id": 12,
    "pricing_model_id": 3,
    "description": "Q1 retail export",
    "datastreams": [
      { "id": 7, "status": true }
    ]
  }'

import requests

res = requests.post(
    "https://console.intuizi.com/api/v2/analyses/activations/create",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
        "Content-Type": "application/json",
        "Accept": "application/json",
        "Idempotency-Key": "<UNIQUE_KEY>",
    },
    json={
        "audience_id": 88,
        "endpoint_connection_id": 12,
        "pricing_model_id": 3,
        "description": "Q1 retail export",
        "datastreams": [{"id": 7, "status": True}],
    },
)
activation_id = res.json()["data"][0]["id"]

const res = await fetch(
  "https://console.intuizi.com/api/v2/analyses/activations/create",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer <YOUR_TOKEN>",
      "Content-Type": "application/json",
      Accept: "application/json",
      "Idempotency-Key": "<UNIQUE_KEY>",
    },
    body: JSON.stringify({
      audience_id: 88,
      endpoint_connection_id: 12,
      pricing_model_id: 3,
      description: "Q1 retail export",
      datastreams: [{ id: 7, status: true }],
    }),
  }
);
const activationId = (await res.json()).data[0].id;

$res = Http::withToken('<YOUR_TOKEN>')->acceptJson()
    ->withHeaders(['Idempotency-Key' => '<UNIQUE_KEY>'])
    ->post('https://console.intuizi.com/api/v2/analyses/activations/create', [
        'audience_id' => 88,
        'endpoint_connection_id' => 12,
        'pricing_model_id' => 3,
        'description' => 'Q1 retail export',
        'datastreams' => [['id' => 7, 'status' => true]],
    ]);
$activationId = $res->json('data.0.id');

Response

The response never includes the endpoint JSON, credentials, result links or device identifiers. created_by, partner and pricing_model are always objects (empty {} when they cannot be resolved). filters echoes the frequency filter the export applies (freq_min / freq_max only apply when freq_limit is true) and filter_hash the preview hash the activation was created with (null when none was sent).

{
  "status": "success",
  "code": 201,
  "message": "Resource created successfully.",
  "data": [
    {
      "id": 501,
      "description": "Q1 retail export",
      "status": { "id": 100, "name": "Initiating" },
      "audience": { "id": 88, "name": "Coffee Buyers NYC" },
      "created_by": { "name": "Jane Doe", "email": "jane.doe@acme.example" },
      "project": { "id": 4, "name": "Retail 2025" },
      "partner": { "name": "Acme DSP", "description": "Programmatic DSP" },
      "pricing_model": { "name": "CPM", "price": 2.5 },
      "datastreams": [],
      "filters": { "freq_limit": false, "freq_min": null, "freq_max": null },
      "filter_hash": null,
      "created_at": "2025-02-01 12:00:00",
      "updated_at": "2025-02-01 12:00:00"
    }
  ]
}

Idempotency

The optional Idempotency-Key header makes a create safe to retry. The key is caller-generated: any unique string up to 255 characters (a UUID v4 is typical), one per logical create - reuse it only when retrying that same request. The first request with a given key runs normally and the successful (2xx) response is cached per caller. A retry with the same key and the same body replays the stored response verbatim with an Idempotency-Replayed: true header, so no duplicate activation is created. A retry with the same key but a different body returns 409 Conflict. See Idempotency for the full replay semantics and the eight endpoints that honor the header.

Preview Activation

GET /api/v2/analyses/activations/preview

Read-only dry run of the frequency filter an activation would apply to a Completed audience. It returns the exact device count the Audience Manager shows as Limit Audience for the same Freq. Range: the audience’s stored frequency histogram (distinct visit days -> devices) summed over the inclusive [freq_min, freq_max] range, which is the same predicate the export applies. Alongside the count you get the histogram, its valid bounds, the audience total, the read-only recency window, the audience eligibility and a canonical filter_hash. Nothing is created, queued, exported, scheduled or billed - call it once per candidate range.

The audience must be 104 Completed and built with a frequency analysis - Visitation Frequency, Apps Frequency or Web Frequency in the Audience Manager, or the matching analyses key on Create Audience. Any other audience - a day-part frequency analysis, a lookalike or cohort, an audience built without a frequency analysis - is refused; the filter is never approximated. For a worked agent session see Preview, then Activate.

Recency is not an input: the date window is fixed by the audience definition and echoed read-only as recency. The preview accepts exactly the three parameters below; any other parameter is rejected.

Auth: bearer token + Accept: application/json. Rate limit: read bucket (120 requests/min).

Query parameters

Field	Type	Required	Description
`audience_id`	integer	Yes	A Completed audience owned by your company, built with exactly one frequency analysis (see Frequency analyses).
`freq_min`	integer	Yes	Lowest distinct visit-day count to include (inclusive). Must be at least `frequency_bounds.min` - `1` for a “1+” range, `2` for “2+”.
`freq_max`	integer	Yes	Highest distinct visit-day count to include (inclusive). Must not exceed `frequency_bounds.max`; use that bound for an open-ended “N+” range.

curl "https://console.intuizi.com/api/v2/analyses/activations/preview?audience_id=88&freq_min=2&freq_max=5" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Accept: application/json"

import requests

res = requests.get(
    "https://console.intuizi.com/api/v2/analyses/activations/preview",
    params={"audience_id": 88, "freq_min": 2, "freq_max": 5},
    headers={"Authorization": "Bearer <YOUR_TOKEN>", "Accept": "application/json"},
)
preview = res.json()["data"][0]
filtered_count, filter_hash = preview["filtered_count"], preview["filter_hash"]

const params = new URLSearchParams({ audience_id: 88, freq_min: 2, freq_max: 5 });
const res = await fetch(
  `https://console.intuizi.com/api/v2/analyses/activations/preview?${params}`,
  { headers: { Authorization: "Bearer <YOUR_TOKEN>", Accept: "application/json" } }
);
const preview = (await res.json()).data[0];
const { filtered_count, filter_hash } = preview;

$res = Http::withToken('<YOUR_TOKEN>')->acceptJson()
    ->get('https://console.intuizi.com/api/v2/analyses/activations/preview', [
        'audience_id' => 88,
        'freq_min' => 2,
        'freq_max' => 5,
    ]);
$preview = $res->json('data.0');

Response

filtered_count is exact. source_count is the audience total shown on the audience itself (an approximate distinct count, about 2.3% standard error) and histogram_total is the exact sum of the histogram, so the two can differ slightly; a [1, frequency_bounds.max] range returns histogram_total. as_of is when the audience’s stored results were last updated.

To activate exactly what was previewed, send the same audience_id, freq_min and freq_max with freq_limit: true and the returned filter_hash to Create Activation; the activation read then echoes both.

{
  "status": "success",
  "code": 200,
  "message": "Resource fetched successfully.",
  "data": [
    {
      "audience": {
        "id": 88,
        "name": "Coffee Buyers NYC",
        "status": { "id": 104, "name": "Completed" },
        "is_activation_allowed": true,
        "eligibility": {
          "allowed": true,
          "reasons": [],
          "metrics": { "unique_eids": 5100, "unique_scids": null, "eid_scid_ratio": null, "is_affinity": false }
        }
      },
      "dataset_type": "POI",
      "analysis_type": "frequency",
      "recency": [
        { "dataset_type": "POI", "start_date": "06/01/2026", "end_date": "07/31/2026" }
      ],
      "source_count": 5100,
      "histogram_total": 5000,
      "filtered_count": 2000,
      "frequency_bounds": { "min": 1, "max": 5 },
      "histogram": [
        { "index": 1, "counts": 3000 },
        { "index": 2, "counts": 1200 },
        { "index": 3, "counts": 500 },
        { "index": 5, "counts": 300 }
      ],
      "applied_filters": { "freq_limit": true, "freq_min": 2, "freq_max": 5 },
      "filter_hash": "sha256:4f9d0c7e1b2a8d3f6e5c4b3a2918f7e6d5c4b3a291807f6e5d4c3b2a19180706",
      "method": "histogram_sum",
      "as_of": "2026-08-01 06:12:44",
      "limitations": [
        "filtered_count is the exact number of devices whose distinct visit-day count inside the audience date window falls within [freq_min, freq_max] (both inclusive) - the same figure the Audience Manager shows as Limit Audience for that Freq. Range, and the same predicate the export applies.",
        "source_count is the audience total shown on the audience itself (an approximate distinct count, about 2.3% standard error); histogram_total is the exact sum of the frequency histogram, so the two can differ slightly. A [1, max] range returns histogram_total."
      ]
    }
  ]
}

List Activations

GET /api/v2/analyses/activations/index

Lists the activations owned by your company, most recent first, paginated.

Auth: bearer token + Accept: application/json. Rate limit: read bucket (120 requests/min).

Query parameters

Field	Type	Required	Description
`per_page`	integer	No	Items per page. Defaults to 25, capped at 100.
`page`	integer	No	Page number (standard pagination).
`search`	string	No	Optional free-text filter on the activation description (case-insensitive contains).

curl "https://console.intuizi.com/api/v2/analyses/activations/index?per_page=25" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Accept: application/json"

import requests

res = requests.get(
    "https://console.intuizi.com/api/v2/analyses/activations/index",
    headers={"Authorization": "Bearer <YOUR_TOKEN>", "Accept": "application/json"},
    params={"per_page": 25},
)
page = res.json()["data"]

const res = await fetch(
  "https://console.intuizi.com/api/v2/analyses/activations/index?per_page=25",
  { headers: { Authorization: "Bearer <YOUR_TOKEN>", Accept: "application/json" } }
);
const page = (await res.json()).data;

Response

{
  "status": "success",
  "code": 200,
  "message": "Resources fetched successfully.",
  "data": {
    "items": [
      {
        "id": 501,
        "description": "Q1 retail export",
        "status": { "id": 104, "name": "Completed" },
        "audience": { "id": 88, "name": "Coffee Buyers NYC" },
        "created_by": { "name": "Jane Doe", "email": "jane.doe@acme.example" },
        "project": { "id": 4, "name": "Retail 2025" },
        "partner": { "name": "Acme DSP", "description": "Programmatic DSP" },
        "pricing_model": { "name": "CPM", "price": 2.5 },
        "datastreams": [
          { "name": "match_file", "status": "success", "results": { "uri": "s3://bucket/path/output.csv" } }
        ],
        "created_at": "2025-02-01 12:00:00",
        "updated_at": "2025-02-02 09:30:00"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 25,
      "total": 1,
      "last_page": 1
    }
  }
}

Get Activation

GET /api/v2/analyses/activations/{id}

Retrieves a single activation by id.

The same read is also available at GET /api/v2/my-data/activations/{id} for backward compatibility; both return the identical response shape.

Auth: bearer token + Accept: application/json. Rate limit: read bucket (120 requests/min).

Path parameters

Field	Type	Required	Description
`id`	integer	Yes	The activation id to fetch.

curl "https://console.intuizi.com/api/v2/analyses/activations/501" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Accept: application/json"

import requests

res = requests.get(
    "https://console.intuizi.com/api/v2/analyses/activations/501",
    headers={"Authorization": "Bearer <YOUR_TOKEN>", "Accept": "application/json"},
)
activation = res.json()["data"][0]

const res = await fetch(
  "https://console.intuizi.com/api/v2/analyses/activations/501",
  { headers: { Authorization: "Bearer <YOUR_TOKEN>", Accept: "application/json" } }
);
const activation = (await res.json()).data[0];

Response

Each entry in datastreams[] carries a name, a status, an always-object results ({ "uri": "s3://..." } or { "gs://..." } when an output file is available, else {}), and an error string only when the datastream failed. The name is the stream’s internal slug, not the name Get Datastreams prints. The status is success for a delivered stream, failed when it failed, or skipped when it cannot run on the audience’s data, and the last two carry an error. Output URIs are normalized to their s3:// or gs:// form. Storage locations and URLs are removed from the error, and an error passed through from the query engine or cloud storage is cut to its first sentence, which states the reason.

{
  "status": "success",
  "code": 200,
  "message": "Resource fetched successfully.",
  "data": [
    {
      "id": 501,
      "description": "Q1 retail export",
      "status": { "id": 104, "name": "Completed" },
      "audience": { "id": 88, "name": "Coffee Buyers NYC" },
      "created_by": { "name": "Jane Doe", "email": "jane.doe@acme.example" },
      "project": { "id": 4, "name": "Retail 2025" },
      "partner": { "name": "Acme DSP", "description": "Programmatic DSP" },
      "pricing_model": { "name": "CPM", "price": 2.5 },
      "datastreams": [
        {
          "name": "match_file",
          "status": "success",
          "results": { "uri": "s3://bucket/path/output.csv" }
        }
      ],
      "filters": { "freq_limit": true, "freq_min": 2, "freq_max": 5 },
      "filter_hash": "sha256:4f9d0c7e1b2a8d3f6e5c4b3a2918f7e6d5c4b3a291807f6e5d4c3b2a19180706",
      "created_at": "2025-02-01 12:00:00",
      "updated_at": "2025-02-02 09:30:00"
    }
  ]
}

Delete Activation

POST /api/v2/analyses/activations/delete-by-id

Soft-deletes an activation.

Auth: bearer token + Accept: application/json + Content-Type: application/json. Rate limit: write bucket (30 requests/min).

Body

Field	Type	Required	Description
`id`	integer	Yes	The activation id to delete. Must be owned by your company.

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

import requests

res = requests.post(
    "https://console.intuizi.com/api/v2/analyses/activations/delete-by-id",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
        "Content-Type": "application/json",
        "Accept": "application/json",
    },
    json={"id": 501},
)

const res = await fetch(
  "https://console.intuizi.com/api/v2/analyses/activations/delete-by-id",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer <YOUR_TOKEN>",
      "Content-Type": "application/json",
      Accept: "application/json",
    },
    body: JSON.stringify({ id: 501 }),
  }
);

Response

{
  "status": "success",
  "code": 200,
  "message": "Resource deleted successfully.",
  "data": []
}

Audiences Cohorts