# Cohorts


Import your own identifiers from a file, an upload, or an audience.
[Conventions](/cli/reference#conventions) apply to every command here.

## Create

Import your own identifiers as a reusable dataset.
See [Create Cohort](/api/v2/cohorts#post-apiv2analysescohortscreate).

Exactly one source: `--file-uri`, `--upload-reference`, or `--audience-id`.
The whole body can come through `--file` instead.

| Flag | Input | Lookup |
| --- | --- | --- |
| `--name` | the cohort name, required for a file source and rejected with `--audience-id` | |
| `--file-uri` | `s3://bucket/path` or `gs://bucket/path`: a file, or a folder of files, in your own S3 or Google Cloud Storage that Intuizi can read | |
| `--upload-reference` | a reference from an upload with `--purpose cohort` | `uploads put` (or `uploads reserve`) |
| `--audience-id` | a completed audience | `audiences list` |
| `--file-format` | how the file is encoded, required for a file source. Unlike on `cohorts preview`, there is no default | |
| `--identifier-type` | what the identifier column holds, required for a file source | |
| `--identifier-column` | column name: letters, digits, `_`, and `-`, required for a file source | `cohorts preview` |
| `--metadata-columns` | a column to keep alongside the identifier, repeatable | `cohorts preview` |
| `--ip-enrichment` | also add devices seen on the same IP addresses as the cohort's devices (Enrich by Household in Audience Manager) | |
| `--device-limit` | cap the devices imported | |
| `--project-id` | the project to file it under, for a file or upload source. Rejected with `--audience-id`, whose cohort takes the audience's project | `projects list` |
| `--dry-run` | print the body, create nothing | |
| `--file` | the whole request body, or `-` for stdin. Not combined with the flags above | |

The accepted `--file-format` and `--identifier-type` values are on
[Create Cohort](/api/v2/cohorts#post-apiv2analysescohortscreate).

A `--file-uri` ending `.csv`, `.gz`, or `.parquet` is imported as one file, and
anything else as a folder, even when it names a single file. The match is
case-sensitive, so `Q3.CSV` imports as a folder. The same rule applies to
`--upload-reference`, through the name the file was uploaded under (the
`uploads put` argument, or `--filename` on `uploads reserve`), cut to its first
100 characters. Rename a file to end `.csv`, `.gz`, or `.parquet` before
uploading it, because a preview reads the upload whatever its name. No credentials
travel with the request, so the location must already be readable by Intuizi.
Your Account Manager can help set that up.

An audience source takes the audience's own name and project, so `--name` and
`--project-id` are rejected with it, as are the flags that describe a file
import. A regular audience yields at most one cohort, and a Lookalike Model
audience can yield several.

```bash
intuizi cohorts create --name "Q3 customers" \
  --file-uri s3://example-bucket/cohorts/q3.csv --file-format csv \
  --identifier-type hem_sha256 --identifier-column email_sha256

intuizi cohorts create --audience-id <id> --device-limit 1000
```

No flag writes the other limits. Capping an audience cohort by visit
frequency, by distance or, for a Lookalike Model, by score range instead of by
device count needs the whole body through `--file`, and so does Match
Strictness (`max_devices_per_ip`) on an SCID file import. See
[Create from an audience](/api/v2/cohorts#create-from-an-audience) for the
audience body.

A create returns as soon as the import is queued, and no cohort command takes
`--wait`. Re-run `intuizi cohorts show <id>` until the status reaches `4`
Completed, as the create's note on stderr says. The table shows the status name, and `--json` gives the id at
`.data.status.id`. Status `5` Not Available means the import failed: stop
polling and fix the cause before creating again. A cohort that failed before
failures were reported as `5` can show `Unknown` instead, and has failed too.
For a `--file-uri` source, check the file and run the create again. For
an `--upload-reference` source, upload the file again for a new reference,
because the failed create used the old one up. A regular audience keeps its
failed cohort, so run `intuizi cohorts delete <id>` before creating from that
audience again. A Lookalike Model audience needs no delete. See
[Cohort status scale](/concepts/status-codes#3-cohort-status-scale-1-5).

## Preview

Read the first rows of a staged file and report its columns, so
`--identifier-column` can be chosen with confidence.
See [Preview Cohort File](/api/v2/cohorts#post-apiv2analysescohortspreview).

| Flag | Input | Lookup |
| --- | --- | --- |
| `--file-uri` | `s3://bucket/path` or `gs://bucket/path`: a file, or a folder of files, in your own S3 or Google Cloud Storage that Intuizi can read | |
| `--upload-reference` | a reference from an upload with `--purpose cohort` | `uploads put` (or `uploads reserve`) |
| `--file-format` | `csv` (the default) or `gzip`. The format is not detected, so pass `gzip` for a compressed file. Parquet files cannot be previewed | |
| `--file` | the whole request body, or `-` for stdin. Not combined with the flags above | |

Exactly one of `--file-uri` or `--upload-reference`, unless the whole body
comes through `--file`. A preview returns sample rows rather than a resource,
so `--quiet` is rejected on it.

A preview reads the file at a `--file-uri` whatever its suffix, and falls back
to a folder only when no file is there. The create goes by the suffix alone,
so a single file needs one of the suffixes above to import as a file.

```bash
intuizi cohorts preview --file-uri s3://example-bucket/cohorts/q3.csv
```

## List

Page through the cohorts in your account.
See [List Cohorts](/api/v2/cohorts#get-apiv2analysescohortsindex).

| Flag | Input |
| --- | --- |
| `--search` | contains match on the cohort name |
| `--page` `--per-page` | page through the results |

## Show

Read one cohort by id, including its import state.
See [Get Cohort](/api/v2/cohorts#get-apiv2analysescohortsid).

A cohort moves through `1` Uploading, `2` Initiating, `3` Processing, and `4`
Completed, a scale of its own rather than the audience one. A failed import
ends at `5` Not Available instead. Read `.data.status.id` from `--json` when
scripting. See [Status Codes](/concepts/status-codes).

## Delete

Remove one cohort. This cannot be undone. The cohort's stored 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. Delete
or deactivate those schedules, and deliver those audiences, before you delete
the cohort.
See [Delete Cohort](/api/v2/cohorts#post-apiv2analysescohortsdelete-by-id).

| Flag | Input |
| --- | --- |
| `--yes` | skip the confirmation prompt |

{{< cards >}}
  {{< card link="/developers/cli/reference/activations/" title="Activations" subtitle="Deliver an audience to an endpoint connection." >}}
  {{< card link="/developers/cli/reference/schedules/" title="Schedules" subtitle="Rebuild an audience on a recurring window." >}}
{{< /cards >}}