Cohorts

Create cohorts from files in your own cloud storage - or from files you upload to us via the upload flow - list them and poll their status. A completed cohort is used as a Cohorts dataset on the Create Audience surface via cohort_id. Cohort creation is asynchronous: the create call returns immediately with a new id, and you poll the get endpoint until the cohort reaches 4 Completed.

All cohort 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); the create uses the write bucket (30 requests/min per caller).

Create Cohort

POST /api/v2/analyses/cohorts/create

Creates a cohort from a CSV, GZIP or Parquet file - either a file (or folder of files) in your own AWS S3 or Google Cloud Storage (file_uri), or a file you uploaded via the upload flow (upload_reference, reserved with purpose cohort). Send exactly one of the two. No credentials travel in the request: a cloud location must already be readable by Intuizi’s processing account - your Account Manager can help set that up. The cohort is queued asynchronously; poll GET /api/v2/analyses/cohorts/{id} for its status.

Not sure which column holds your identifiers? Call Preview Cohort File first.

Auth: bearer token + Accept: application/json + Content-Type: application/json. Rate limit: write bucket (30 requests/min). Optional: Idempotency-Key header makes this create safe to retry - see Idempotency.

Body

curl -X POST "https://console.intuizi.com/api/v2/analyses/cohorts/create" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: <UNIQUE_KEY>" \
  -d '{
    "name": "Loyalty program members",
    "file_uri": "s3://my-bucket/exports/devices.csv",
    "file_format": "csv",
    "identifier_type": "maid",
    "identifier_column": "maid"
  }'

import requests

res = requests.post(
    "https://console.intuizi.com/api/v2/analyses/cohorts/create",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
        "Content-Type": "application/json",
        "Accept": "application/json",
        "Idempotency-Key": "<UNIQUE_KEY>",
    },
    json={
        "name": "Loyalty program members",
        "file_uri": "s3://my-bucket/exports/devices.csv",
        "file_format": "csv",
        "identifier_type": "maid",
        "identifier_column": "maid",
    },
)
cohort_id = res.json()["data"][0]["id"]

const res = await fetch(
  "https://console.intuizi.com/api/v2/analyses/cohorts/create",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer <YOUR_TOKEN>",
      "Content-Type": "application/json",
      Accept: "application/json",
      "Idempotency-Key": "<UNIQUE_KEY>",
    },
    body: JSON.stringify({
      name: "Loyalty program members",
      file_uri: "s3://my-bucket/exports/devices.csv",
      file_format: "csv",
      identifier_type: "maid",
      identifier_column: "maid",
    }),
  }
);
const cohortId = (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/cohorts/create', [
        'name' => 'Loyalty program members',
        'file_uri' => 's3://my-bucket/exports/devices.csv',
        'file_format' => 'csv',
        'identifier_type' => 'maid',
        'identifier_column' => 'maid',
    ]);
$cohortId = $res->json('data.0.id');

Response

{
  "status": "success",
  "code": 201,
  "message": "Resource created successfully.",
  "data": [
    {
      "id": 42,
      "name": "Loyalty program members",
      "status": { "id": 2, "name": "Initiating" },
      "total_eids": null,
      "project": null,
      "source": "file",
      "source_audience": null,
      "created_at": "2025-07-18 12:00:00",
      "updated_at": "2025-07-18 12:00:00"
    }
  ]
}

Create from an audience

The same POST /api/v2/analyses/cohorts/create endpoint also builds a cohort from a completed audience instead of a file. Send source set to audience and an audience_id. The audience must be owned by your company and be 104 Completed. A regular audience can be turned into at most one cohort; a Lookalike Model audience can back several (one per score range). The cohort takes its name and project from the audience, so name is not required on this path.

Choose one limit for the cohort:

• Frequency - set freq_limit to true with freq_min and freq_max (and optionally is_day_part) to keep devices by how often they were seen.
• Distance - set distance_limit to true with distance (in meters) to keep devices within a radius.
• Score (Lookalike Model audiences only) - set score_limit to true with min_score and max_score to keep devices inside a model score range. The bounds are on the 0 to 1 score scale in steps of 0.1, the same bands the Audience Manager’s Precision-to-Reach slider shows for the model; min_score may not exceed max_score. The cohort keeps the best-scored EIDs first, and an optional device_limit caps how many it keeps.
• Device - send none of the above for a plain device limit; add an optional device_limit to cap the number of devices kept. On a Lookalike Model audience the best-scored EIDs are kept first.

Like the file create, this is queued asynchronously - poll GET /api/v2/analyses/cohorts/{id} until the cohort reaches 4 Completed.

Auth: bearer token + Accept: application/json + Content-Type: application/json. Rate limit: write bucket (30 requests/min). Optional: Idempotency-Key header makes this create safe to retry - see Idempotency.

Body

curl -X POST "https://console.intuizi.com/api/v2/analyses/cohorts/create" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: <UNIQUE_KEY>" \
  -d '{
    "source": "audience",
    "audience_id": 8123,
    "freq_limit": true,
    "freq_min": 2,
    "freq_max": 10
  }'

import requests

res = requests.post(
    "https://console.intuizi.com/api/v2/analyses/cohorts/create",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
        "Content-Type": "application/json",
        "Accept": "application/json",
        "Idempotency-Key": "<UNIQUE_KEY>",
    },
    json={
        "source": "audience",
        "audience_id": 8123,
        "freq_limit": True,
        "freq_min": 2,
        "freq_max": 10,
    },
)
cohort_id = res.json()["data"][0]["id"]

const res = await fetch(
  "https://console.intuizi.com/api/v2/analyses/cohorts/create",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer <YOUR_TOKEN>",
      "Content-Type": "application/json",
      Accept: "application/json",
      "Idempotency-Key": "<UNIQUE_KEY>",
    },
    body: JSON.stringify({
      source: "audience",
      audience_id: 8123,
      freq_limit: true,
      freq_min: 2,
      freq_max: 10,
    }),
  }
);
const cohortId = (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/cohorts/create', [
        'source' => 'audience',
        'audience_id' => 8123,
        'freq_limit' => true,
        'freq_min' => 2,
        'freq_max' => 10,
    ]);
$cohortId = $res->json('data.0.id');

The response is the same shape as the file create above, with source set to audience and source_audience naming the audience the cohort is built from.

Preview Cohort File

POST /api/v2/analyses/cohorts/preview

Reads only a bounded prefix (about 64 KB) of a cohort source file and returns the column headers, up to 20 sample rows keyed by column name, and the number of complete rows found in the prefix (not the file total). Use it to confirm identifier_column and metadata_columns before creating the cohort, instead of finding out after the import fails.

Takes the same source the create takes: file_uri for a file in your own cloud, or upload_reference for a file you uploaded - exactly one of the two. Previewing does not consume an upload_reference.

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

Body

curl -X POST "https://console.intuizi.com/api/v2/analyses/cohorts/preview" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "upload_reference": "upl_01k0p3v9example"
  }'

import requests

res = requests.post(
    "https://console.intuizi.com/api/v2/analyses/cohorts/preview",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
        "Content-Type": "application/json",
        "Accept": "application/json",
    },
    json={"upload_reference": "upl_01k0p3v9example"},
)
columns = res.json()["data"][0]["columns"]

const res = await fetch(
  "https://console.intuizi.com/api/v2/analyses/cohorts/preview",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer <YOUR_TOKEN>",
      "Content-Type": "application/json",
      Accept: "application/json",
    },
    body: JSON.stringify({ upload_reference: "upl_01k0p3v9example" }),
  }
);
const columns = (await res.json()).data[0].columns;

$res = Http::withToken('<YOUR_TOKEN>')->acceptJson()
    ->post('https://console.intuizi.com/api/v2/analyses/cohorts/preview', [
        'upload_reference' => 'upl_01k0p3v9example',
    ]);
$columns = $res->json('data.0.columns');

Response

{
  "status": "success",
  "code": 200,
  "message": "Resource fetched successfully.",
  "data": [
    {
      "columns": ["maid", "segment"],
      "samples": [
        { "maid": "38f2a9c1-0000-4e6b-9c7d-000000000000", "segment": "gold" }
      ],
      "sample_rows": 214
    }
  ]
}

List Cohorts

GET /api/v2/analyses/cohorts/index

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

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

Query parameters

Response

{
  "status": "success",
  "code": 200,
  "message": "Resources fetched successfully.",
  "data": {
    "items": [
      {
        "id": 42,
        "name": "Loyalty program members",
        "status": { "id": 4, "name": "Completed" },
        "total_eids": 184233,
        "project": null,
        "source": "file",
        "source_audience": null,
        "created_at": "2025-07-18 12:00:00",
        "updated_at": "2025-07-18 12:41:07"
      }
    ],
    "pagination": { "current_page": 1, "per_page": 25, "total": 1, "last_page": 1 }
  }
}

Delete Cohort

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

Deletes one cohort owned by your company. The cohort’s imported data is deleted with it unless it was built from a regular audience that still exists, so a file-imported or Lookalike Model cohort loses its data. Once the data is gone, an audience whose only dataset is this cohort can no longer be activated, and a schedule whose audience uses the cohort fails from its next cycle. Audiences that combine the cohort with other datasets keep their built results.

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

Body

Response

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

Get Cohort

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

Fetches one cohort owned by your company, including its lifecycle status. Poll this after a create until the status reaches 4 Completed - then the cohort id is valid as datasets[].cohort_id on the Create Audience surface - or 5 Not Available, which means the import failed.

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

Path parameters

The cohort statuses:

4 and 5 are final, so stop polling at either. A cohort.failed webhook is sent at 5. A cohort that failed before failures were reported as 5 can still read the error code it failed with, which the API names Unknown. Treat that as a failed import too. What to do after a failed import depends on the source:

• file_uri: fix the file, then create the cohort again.
• upload_reference: the failed create used the reference up, so upload the file again for a new reference.
• audience_id with a regular audience: the failed cohort still counts as the audience’s one cohort, so delete it before creating from that audience again. A Lookalike Model audience needs no delete.

Response

source says how the cohort was created, in the words the create call takes: file (a file in your cloud or an upload), audience (built from an audience, including a Lookalike Model), or pixel (built in the console from a pixel campaign). It is null for cohorts whose origin was not recorded, such as older cohorts.

source_audience names the audience a source: "audience" cohort was built from, as { "id", "name" }. Follow it with Get Audience - for a Lookalike Model, that read’s own source_audience names the seed. It is null for file and pixel cohorts, for cohorts whose origin was not recorded, and when the audience has been deleted or does not belong to your company.

{
  "status": "success",
  "code": 200,
  "message": "Resource fetched successfully.",
  "data": {
    "id": 42,
    "name": "Loyalty program members",
    "status": { "id": 4, "name": "Completed" },
    "total_eids": 184233,
    "project": null,
    "source": "file",
    "source_audience": null,
    "created_at": "2025-07-18 12:00:00",
    "updated_at": "2025-07-18 12:41:07"
  }
}