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
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Cohort name (max 255 chars). |
project_id | integer | No | A project id owned by your company to file the cohort under. |
file_uri | string | One of | s3://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_reference | string | One of | The 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_format | string | Yes | csv (uncompressed), gzip (compressed) or parquet. |
identifier_type | string | Yes | What 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_column | string | Yes | The column in your file holding the identifier. Letters, numbers, hyphens and underscores only. |
metadata_columns | string[] | No | Extra columns from your file to keep alongside the identifiers. |
ip_enrichment | boolean | No | Also add devices seen on the same IP addresses as the cohort’s devices (Enrich by Household in the Audience Manager). Defaults to false. |
device_limit | integer | No | Cap the number of devices the cohort keeps. Omit for no cap. |
max_devices_per_ip | integer | No | SCID 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_months | integer | No | SCID 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_filters | object[] | No | csv 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_limittotruewithfreq_minandfreq_max(and optionallyis_day_part) to keep devices by how often they were seen. - Distance - set
distance_limittotruewithdistance(in meters) to keep devices within a radius. - Score (Lookalike Model audiences only) - set
score_limittotruewithmin_scoreandmax_scoreto 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_scoremay not exceedmax_score. The cohort keeps the best-scored EIDs first, and an optionaldevice_limitcaps how many it keeps. - Device - send none of the above for a plain device limit; add an
optional
device_limitto 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
| Field | Type | Required | Description |
|---|---|---|---|
source | string | Yes | Set to audience to build from an audience. Defaults to file. |
audience_id | integer | Yes | A 104 Completed audience owned by your company. A regular audience yields at most one cohort; a Lookalike Model audience can yield several. |
project_id | integer | No | Does 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_limit | boolean | No | Keep devices by visit frequency. Requires freq_min and freq_max. |
freq_min | integer | Conditional | Minimum visit frequency. Required when freq_limit is true. |
freq_max | integer | Conditional | Maximum visit frequency. Required when freq_limit is true. |
is_day_part | boolean | No | Apply the frequency window per day-part. |
distance_limit | boolean | No | Keep devices within a radius. Requires distance. |
distance | integer | Conditional | Radius in meters. Required when distance_limit is true. |
score_limit | boolean | No | Lookalike Model audiences only. Keep devices inside a model score range. Requires min_score and max_score. |
min_score | number | Conditional | Lower score bound, 0 to 1 in steps of 0.1, at most max_score. Required when score_limit is true. |
max_score | number | Conditional | Upper score bound, 0 to 1 in steps of 0.1. Required when score_limit is true. |
device_limit | integer | No | Cap 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
| Field | Type | Required | Description |
|---|---|---|---|
file_uri | string | One of | s3://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_reference | string | One of | The upload_reference from Create an Upload (purpose cohort), after the file was PUT. Send either this or file_uri, not both. |
file_format | string | No | csv (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
| Field | Type | Required | Description |
|---|---|---|---|
file_uri | string | One of | s3://bucket/path or gs://bucket/path, the same locations as the create’s file_uri. Send either this or upload_reference, not both. |
upload_reference | string | One of | The upload_reference from Create an Upload (purpose cohort), after the file was PUT. Send either this or file_uri, not both. |
file_format | string | Yes | csv (uncompressed) or gzip (compressed). A Parquet file cannot be filtered, so it is not scanned. |
identifier_column | string | Yes | The column the create will read the identifiers from. Letters, numbers, hyphens and underscores only. |
columns | string[] | Yes | 1 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
| Field | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | The scan id from Scan Cohort File. |
Scan status
status.id | status.name | Meaning |
|---|---|---|
2 | Initiating | The scan is queued. |
3 | Processing | The file is being read and counted. |
4 | Completed | The counts are ready. |
5 | Not Available | The 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
| Field | Type | Description |
|---|---|---|
id | integer | The scan id. |
status | object | {id, name}, see the table above. |
total_rows | integer | The data rows of the whole file, the header not included. null until 4. |
columns | string[] | The scanned columns, in the order you sent them. |
combinations | object[] | 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. |
truncated | boolean | true when the file has more than 1,000 combinations, so the list and the sums are incomplete. null until 4. |
message | string | Why 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
| 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 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
| Field | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | The 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
| Field | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | The cohort id to fetch. |
The cohort statuses:
| Status | Name | Meaning |
|---|---|---|
1 | Uploading | The cohort row exists; the import has not been queued yet. |
2 | Initiating | The import is queued for processing. |
3 | Processing | The file is being imported and matched. |
4 | Completed | The cohort is ready to use in an audience. |
5 | Not Available | The 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_idwith 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"
}
}