Skip to content

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. A file can also sit in your organization’s folder in the Intuizi delivery bucket, the us-west-2 URI that came with your Intuizi AWS credentials (s3://intuizi-export-delivery/<your folder>/), for example s3://intuizi-export-delivery/<your folder>/exports/devices.csv. Other Intuizi buckets are not a source. 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. Does the file hold more rows than the cohort should take? Count its rows by column value with Scan Cohort File, then keep only the rows you want with row_filters.

Creating a cohort is a gated capability: it requires additional permissions which need to be approved by your Account Manager.

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

FieldTypeRequiredDescription
namestringYesCohort name (max 255 chars).
project_idintegerNoA project id owned by your company to file the cohort under.
file_uristringOne ofs3://bucket/path or gs://bucket/path - the file (or folder of files) to import from your own cloud. Must include a bucket and a path (e.g. s3://my-bucket/exports/devices.csv). In an Intuizi delivery bucket the path must be inside the delivery folder Intuizi set up for your organization, and other Intuizi buckets are not a source. A folder of a third-party bucket that Intuizi reads data from is not a source either, nor is a path read as a folder that would take in such a folder. The bucket is a standard bucket name, not an access point alias. The path has no empty segment (//), no . or .. segment, and no backslash or control character. A final / marks a folder. A URI ending in .csv, .gz or .parquet is read as a single file, and anything else is read as a folder. The match is case-sensitive, so Q3.CSV is read as a folder. Send either this or upload_reference, not both.
upload_referencestringOne ofThe upload_reference from Create an Upload (purpose cohort), after the file was PUT to the presigned URL. One-shot: a reference can create exactly one cohort. The same suffix rule as file_uri applies to the filename the upload was created with, cut to its first 100 characters: only a name ending in .csv, .gz or .parquet (case-sensitive) is read as a single file, and anything else as a folder. Send either this or file_uri, not both.
file_formatstringYescsv (uncompressed), gzip (compressed) or parquet.
identifier_typestringYesWhat the identifier column contains: eid, eid_md5, maid, ip, hem_plaintext, scid, hem_md5, hem_sha1 or hem_sha256. Plain-text emails, IPs and MAIDs are encrypted and hashed before analysis begins.
identifier_columnstringYesThe column in your file holding the identifier. Letters, numbers, hyphens and underscores only.
metadata_columnsstring[]NoExtra columns from your file to keep alongside the identifiers.
ip_enrichmentbooleanNoAlso add devices seen on the same IP addresses as the cohort’s devices (Enrich by Household in the Audience Manager). Defaults to false.
device_limitintegerNoCap the number of devices the cohort keeps. Omit for no cap.
max_devices_per_ipintegerNoSCID files only. Match Strictness, 1 (very strict) to 5 (more reach): each person contributes at most level x 2 of their top-ranked devices. Defaults to 3 (top 6 devices per person). Ignored for other identifier types.
match_monthsintegerNoSCID files only. Months of SCID links to match, 1 (latest month) to 3. Each SCID uses its most recent month in that window. Defaults to 1. Ignored for other identifier types.
row_filtersobject[]Nocsv and gzip files only. Keep only the rows whose columns hold the chosen values: a list of {"column": "...", "values": ["...", ...]}. A row is kept when, for every entry, its column holds one of that entry’s values (all entries must match, any value of an entry matches). Values match exactly, case included, and "" keeps the rows with an empty cell. At most 5 entries, each column once and never identifier_column, with 1 to 100 distinct values of at most 255 characters each. A column the file does not have fails the cohort at 5 Not Available. Omit it to keep every row. See Keep only some rows.
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"
  }'

Response

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

Keep only some rows

One file can hold several audiences, for example one row per person and channel, with a column that says which group each row belongs to. Count the rows of each value first with Scan Cohort File, then send the values to keep as row_filters on the create. This body keeps the rows whose channel is Meta and whose cell is meta_holdout or dsp_holdout:

{
  "name": "Boston holdout - Meta",
  "file_uri": "s3://my-bucket/exports/holdout_assignments.csv",
  "file_format": "csv",
  "identifier_type": "scid",
  "identifier_column": "stagwell_consumer_id",
  "row_filters": [
    { "column": "channel", "values": ["Meta"] },
    { "column": "cell", "values": ["meta_holdout", "dsp_holdout"] }
  ]
}

The scan counts rows, and the cohort counts identifiers: when two kept rows hold the same identifier, the cohort has one identifier fewer than the rows the scan counted. row_filters is refused with file_format parquet.

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. It needs the same permissions as a cohort from a file. row_filters applies to a file source only: a create from an audience that sends it is refused with 422.

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

FieldTypeRequiredDescription
sourcestringYesSet to audience to build from an audience. Defaults to file.
audience_idintegerYesA 104 Completed audience owned by your company. A regular audience yields at most one cohort; a Lookalike Model audience can yield several.
project_idintegerNoDoes not change the project, since the cohort inherits the audience’s project, but it is still validated: it must be a project owned by your company.
freq_limitbooleanNoKeep devices by visit frequency. Requires freq_min and freq_max.
freq_minintegerConditionalMinimum visit frequency. Required when freq_limit is true.
freq_maxintegerConditionalMaximum visit frequency. Required when freq_limit is true.
is_day_partbooleanNoApply the frequency window per day-part.
distance_limitbooleanNoKeep devices within a radius. Requires distance.
distanceintegerConditionalRadius in meters. Required when distance_limit is true.
score_limitbooleanNoLookalike Model audiences only. Keep devices inside a model score range. Requires min_score and max_score.
min_scorenumberConditionalLower score bound, 0 to 1 in steps of 0.1, at most max_score. Required when score_limit is true.
max_scorenumberConditionalUpper score bound, 0 to 1 in steps of 0.1. Required when score_limit is true.
device_limitintegerNoCap the number of devices the cohort keeps. Applies with score_limit (best scores first) or when no other limit is set.
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
  }'

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. It needs the same permissions as Create Cohort.

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

Body

FieldTypeRequiredDescription
file_uristringOne ofs3://bucket/path or gs://bucket/path - a file, or a folder of files, readable by Intuizi’s processing account. It takes the same locations as the create’s file_uri, so in an Intuizi delivery bucket only a path inside your organization’s delivery folder, and no folder of a third-party bucket that Intuizi reads data from. The preview reads the file at the URI whatever its name, and reads a folder only when the URI ends in / or no file is there, taking the header from its first data file (hidden _/.-prefixed files such as Spark’s _SUCCESS are skipped). The create goes by suffix instead, so a single file must end in .csv, .gz or .parquet to import as a file. Send either this or upload_reference, not both.
upload_referencestringOne ofThe upload_reference from Create an Upload (purpose cohort), after the file was PUT. Send either this or file_uri, not both.
file_formatstringNocsv (default) or gzip. Parquet files cannot be previewed.
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"
  }'

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
    }
  ]
}

Scan Cohort File

POST /api/v2/analyses/cohorts/scan

Counts the rows of a cohort source file by the values of 1 to 5 of its columns, before the cohort is created, so the row_filters of Create Cohort can be chosen from real counts. The whole file is read, not a prefix: a scan runs asynchronously and usually takes under a minute. The scan answers 202 with the scan id at status 2 Initiating. Poll Get Cohort File Scan until the status is 4 Completed or 5 Not Available.

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. Scanning does not consume an upload_reference. Nothing is created but the scan, which is kept for 24 hours. Scanning the same file by the same columns (in the same order) again returns the scan already running, or the one that finished within the last hour, instead of starting a new one. A scan that ended Not Available is never reused. An organization runs a few scans at once (see Limits). It needs the same permissions as Create Cohort.

Auth: bearer token + Accept: application/json + Content-Type: application/json. Rate limit: write bucket (30 requests/min), and 10 scans a minute per caller. The Idempotency-Key header is ignored: the counts hold the file’s values, so they are never kept in a replay cache. Sending the same request again answers the same scan, as above.

Body

FieldTypeRequiredDescription
file_uristringOne ofs3://bucket/path or gs://bucket/path, the same locations as the create’s file_uri. Send either this or upload_reference, not both.
upload_referencestringOne ofThe upload_reference from Create an Upload (purpose cohort), after the file was PUT. Send either this or file_uri, not both.
file_formatstringYescsv (uncompressed) or gzip (compressed). A Parquet file cannot be filtered, so it is not scanned.
identifier_columnstringYesThe column the create will read the identifiers from. Letters, numbers, hyphens and underscores only.
columnsstring[]Yes1 to 5 distinct column names to count the rows by, exactly as Preview Cohort File returns them, never identifier_column. Any column name the preview returns.
curl -X POST "https://console.intuizi.com/api/v2/analyses/cohorts/scan" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "file_uri": "s3://my-bucket/exports/holdout_assignments.csv",
    "file_format": "csv",
    "identifier_column": "stagwell_consumer_id",
    "columns": ["channel", "cell"]
  }'

Response

{
  "status": "success",
  "code": 202,
  "message": "Resource accepted.",
  "data": [
    {
      "id": 17,
      "status": { "id": 2, "name": "Initiating" },
      "total_rows": null,
      "columns": ["channel", "cell"],
      "combinations": null,
      "truncated": null,
      "message": null
    }
  ]
}

Get Cohort File Scan

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

Fetches one scan owned by your company. Poll it until status.id is 4 Completed or 5 Not Available, waiting a few seconds between reads: a scan usually takes under a minute. A scan is kept for 24 hours after it was made, then it reads as not found.

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

Path parameters

FieldTypeRequiredDescription
idintegerYesThe scan id from Scan Cohort File.

Scan status

status.idstatus.nameMeaning
2InitiatingThe scan is queued.
3ProcessingThe file is being read and counted.
4CompletedThe counts are ready.
5Not AvailableThe file could not be counted. message says why, for example a file with one column, or a column the file does not have.

Response fields

FieldTypeDescription
idintegerThe scan id.
statusobject{id, name}, see the table above.
total_rowsintegerThe data rows of the whole file, the header not included. null until 4.
columnsstring[]The scanned columns, in the order you sent them.
combinationsobject[]Each combination of values of columns that occurs in the file, with its row count: {"values": [...], "rows": 123}, the values in the order of columns, an empty cell as "", most rows first, at most 1,000. The rows a single value keeps are the sum of rows over the combinations that hold it. null until 4.
truncatedbooleantrue when the file has more than 1,000 combinations, so the list and the sums are incomplete. null until 4.
messagestringWhy the file could not be counted, at 5. null otherwise.
curl "https://console.intuizi.com/api/v2/analyses/cohorts/scan/17" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Accept: application/json"

Response

{
  "status": "success",
  "code": 200,
  "message": "Resource fetched successfully.",
  "data": [
    {
      "id": 17,
      "status": { "id": 4, "name": "Completed" },
      "total_rows": 2271234,
      "columns": ["channel", "cell"],
      "combinations": [
        { "values": ["Meta", "activate"], "rows": 1856234 },
        { "values": ["TTD", "activate"], "rows": 321346 },
        { "values": ["Meta", "meta_holdout"], "rows": 51022 },
        { "values": ["Meta", "dsp_holdout"], "rows": 42632 }
      ],
      "truncated": false,
      "message": null
    }
  ]
}

Here channel Meta keeps 1,949,888 rows (the sum of its three combinations), and channel Meta with cell meta_holdout or dsp_holdout keeps 93,654.

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

FieldTypeRequiredDescription
per_pageintegerNoItems per page. Defaults to 25, capped at 100.
pageintegerNoPage number (standard pagination).
searchstringNoOptional free-text filter on the cohort name (case-insensitive contains).

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,
        "total_scids": null,
        "matched_scids": null,
        "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

FieldTypeRequiredDescription
idintegerYesThe cohort id to delete. Must be owned by your company.

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

FieldTypeRequiredDescription
idintegerYesThe cohort id to fetch.

The cohort statuses:

StatusNameMeaning
1UploadingThe cohort row exists; the import has not been queued yet.
2InitiatingThe import is queued for processing.
3ProcessingThe file is being imported and matched.
4CompletedThe cohort is ready to use in an audience.
5Not AvailableThe import failed. The cohort cannot be used in an audience.

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.

total_scids and matched_scids are set on a completed SCID file import: total_scids is the number of distinct SCIDs in the file, and matched_scids the number of them with at least one device in the match_months window. They are null for other cohorts and for SCID cohorts built before these fields were added.

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