---
"@context": https://schema.org
"@type": TechArticle
"@id": https://www.twilio.com/docs/cohorts/getting-started#article
headline: Getting started with Twilio Cohorts
description: Get started with Twilio Cohorts. Define filter criteria, create a cohort, generate a snapshot, and retrieve matching profiles.
url: https://www.twilio.com/docs/cohorts/getting-started
inLanguage: en
dateModified: 2026-10-01T16:19:20.000Z
author:
  "@type": Organization
  name: Twilio Developer Education Team
publisher:
  "@type": Organization
  name: Twilio
---

# Getting started with Twilio Cohorts

> \[!IMPORTANT]
>
> Twilio Cohorts is available only to accounts in the Private Beta. Request access to the private beta through [this form](https://airtable.com/appRfMcPhtbqS6n2A/pagrrzSGrvqgGjjEu/form).

## Prerequisites

Before you begin, ensure you have the following:

1. A Twilio account: [Sign up for a free account](https://www.twilio.com/try-twilio).
2. Your API key and secret, available from the [Twilio Console](https://console.twilio.com).
3. A connected profile store containing customer traits and addresses, along with its store identifier (`storeId`). If you don't already have one, create a store in the Twilio Console under **Profiles** or by using the Twilio Profile API. [Create a store](/docs/api/memory/v1/store), and then [add profiles](/docs/api/memory/v1/profile). To segment on custom traits, create a [trait group](/docs/api/memory/v1/trait-group) before you add profiles.

## Authenticate your requests

Cohorts uses standard Twilio HTTP basic auth. Provide your API key and secret as HTTP basic auth credentials on every request.

```bash
curl -X GET 'https://audiences.twilio.com/preview/Cohorts' \
-u $TWILIO_API_KEY:$TWILIO_API_SECRET
```

## Define your first cohort

A cohort is a saved rule. Write your targeting rules using [CEL](https://cel.dev) to filter profile traits and addresses.

```bash
curl -X POST 'https://audiences.twilio.com/preview/Cohorts' \
-H 'Content-Type: application/json' \
-d '{
    "displayName": "Active US customers",
    "description": "US-based customers with an active account",
    "storeType": "TWILIO",
    "storeId": "mem_store_01h9d8r0vte3hz8tykdj329t7r",
    "criteria": "profile.trait.Account.status == \"active\" && profile.trait.Account.country == \"US\"",
    "labels": {
        "key": "value"
    }
}' \
-u $TWILIO_API_KEY:$TWILIO_API_SECRET
```

`storeType` and `storeId` identify which connected profile store to evaluate against. Currently, `storeType` is always `"TWILIO"`. `description` and `labels` are optional.

**Sample response**:

```json
{
  "id": "cmp_cohort_01h9d8r0vte3hz8tykdj329t7r",
  "displayName": "Active US customers",
  "description": "US-based customers with an active account",
  "storeType": "TWILIO",
  "storeId": "mem_store_01h9d8r0vte3hz8tykdj329t7r",
  "criteria": "profile.trait.Account.status == \"active\" && profile.trait.Account.country == \"US\"",
  "labels": {
    "key": "value"
  },
  "createdAt": "2026-01-15T10:00:00Z",
  "updatedAt": "2026-01-15T10:00:00Z"
}
```

To learn more about writing criteria, see [Writing filter criteria](/docs/cohorts/cel/overview).

## Generate a snapshot

A snapshot materializes a point-in-time list of profiles that currently match your cohort criteria. Generating a snapshot starts an asynchronous operation.

```bash
curl -X POST 'https://audiences.twilio.com/preview/CohortSnapshots' \
-H 'Content-Type: application/json' \
-d '{
    "source": {
        "cohortId": "cmp_cohort_01h9d8r0vte3hz8tykdj329t7r"
    },
    "variables": [
        { "expression": "profile.address.email", "displayName": "email" }
    ],
    "labels": {
        "key": "value"
    }
}' \
-u $TWILIO_API_KEY:$TWILIO_API_SECRET
```

The `variables` and `labels` fields are optional. Each `variables` entry projects profile data into the results, keyed by `displayName`. If you omit `variables`, snapshot profile results contain only the profile IDs.

The API responds with an HTTP `202 Accepted` status and returns an operation object you can poll for completion.

**Sample response**:

```json
{
  "operationId": "cmp_operation_01h9d8r0vte3hz8tykdj329t7r",
  "status": "PENDING",
  "statusUrl": "/preview/CohortOperations/cmp_operation_01h9d8r0vte3hz8tykdj329t7r",
  "createdAt": "2026-01-15T10:00:00Z"
}
```

## Poll the operation

Poll the operation URL until its status transitions to `COMPLETED`, `FAILED`, or `CANCELLED`.

```bash
curl -X GET 'https://audiences.twilio.com/preview/CohortOperations/cmp_operation_01h9d8r0vte3hz8tykdj329t7r' \
-u $TWILIO_API_KEY:$TWILIO_API_SECRET
```

**Sample response**:

```json
{
  "operationId": "cmp_operation_01h9d8r0vte3hz8tykdj329t7r",
  "status": "COMPLETED",
  "statusUrl": "/preview/CohortOperations/cmp_operation_01h9d8r0vte3hz8tykdj329t7r",
  "createdAt": "2026-01-15T10:00:00Z",
  "completedAt": "2026-01-15T10:00:04Z",
  "resultUrl": "/preview/CohortSnapshots/cmp_cohortsnapshot_01h9d8r0vte3hz8tykdj329t7r",
  "result": {
    "cohortSnapshotId": "cmp_cohortsnapshot_01h9d8r0vte3hz8tykdj329t7r",
    "profileCount": 15420
  }
}
```

Once the operation status is `COMPLETED`, copy the `cohortSnapshotId` from the `result` block to fetch your profiles.

To learn more, see [Operations](/docs/cohorts/concepts/operations).

## Retrieve matching profiles

Pass the `cohortSnapshotId` to page through the matching customer profiles.

```bash
curl -X GET 'https://audiences.twilio.com/preview/CohortSnapshots/cmp_cohortsnapshot_01h9d8r0vte3hz8tykdj329t7r/Profiles' \
-u $TWILIO_API_KEY:$TWILIO_API_SECRET
```

**Sample response**:

```json
{
  "profiles": [
    {
      "profileId": "mem_profile_01h9d8r0vte3hz8tykdj329t7r",
      "variables": {
        "email": "jane@example.com"
      }
    }
  ],
  "meta": {
    "key": "profiles",
    "pageSize": 50,
    "nextToken": "eyJvZmZzZXQiOjUwfQ"
  }
}
```

If your snapshot matches more profiles than fit on a single page, see [Retrieving profiles](/docs/cohorts/concepts/retrieving-profiles) for details on handling pagination tokens and parallel execution.

## Next steps

* Learn about [Core concepts](/docs/cohorts/concepts/cohorts).
* Read about [Writing filter criteria](/docs/cohorts/cel/overview).
* See how to [Integrate Cohorts with downstream workflows](/docs/cohorts/bulk-messaging-and-email).