Skip to contentSkip to navigationSkip to topbar
Page tools
Useful for sharing or LLM
Accelerate development with AI
On this page
Looking for more inspiration?Visit the

Getting started with Twilio Cohorts

(new)

Beta

Twilio Cohorts is available only to accounts in the Private Beta. Request access to the private beta through this form(link takes you to an external page).

Prerequisites

prerequisites page anchor

Before you begin, ensure you have the following:

  1. A Twilio account: Sign up for a free account(link takes you to an external page).
  2. Your API key and secret, available from the Twilio Console(link takes you to an external page).
  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, and then add profiles. To segment on custom traits, create a trait group before you add profiles.

Authenticate your requests

authenticate-your-requests page anchor

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

1
curl -X GET 'https://audiences.twilio.com/preview/Cohorts' \

2
-u $TWILIO_API_KEY:$TWILIO_API_SECRET

Define your first cohort

define-your-first-cohort page anchor

A cohort is a saved rule. Write your targeting rules using CEL(link takes you to an external page) to filter profile traits and addresses.

1
curl -X POST 'https://audiences.twilio.com/preview/Cohorts' \

2
-H 'Content-Type: application/json' \

3
-d '{

4
    "displayName": "Active US customers",

5
    "description": "US-based customers with an active account",

6
    "storeType": "TWILIO",

7
    "storeId": "mem_store_01h9d8r0vte3hz8tykdj329t7r",

8
    "criteria": "profile.trait.Account.status == \"active\" && profile.trait.Account.country == \"US\"",

9
    "labels": {

10
        "key": "value"

11
    }

12
}' \

13
-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:

1
{

2
  "id": "cmp_cohort_01h9d8r0vte3hz8tykdj329t7r",

3
  "displayName": "Active US customers",

4
  "description": "US-based customers with an active account",

5
  "storeType": "TWILIO",

6
  "storeId": "mem_store_01h9d8r0vte3hz8tykdj329t7r",

7
  "criteria": "profile.trait.Account.status == \"active\" && profile.trait.Account.country == \"US\"",

8
  "labels": {

9
    "key": "value"

10
  },

11
  "createdAt": "2026-01-15T10:00:00Z",

12
  "updatedAt": "2026-01-15T10:00:00Z"

13
}

To learn more about writing criteria, see Writing filter criteria.

Generate a snapshot

generate-a-snapshot page anchor

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

1
curl -X POST 'https://audiences.twilio.com/preview/CohortSnapshots' \

2
-H 'Content-Type: application/json' \

3
-d '{

4
    "source": {

5
        "cohortId": "cmp_cohort_01h9d8r0vte3hz8tykdj329t7r"

6
    },

7
    "variables": [

8
        { "expression": "profile.address.email", "displayName": "email" }

9
    ],

10
    "labels": {

11
        "key": "value"

12
    }

13
}' \

14
-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:

1
{

2
  "operationId": "cmp_operation_01h9d8r0vte3hz8tykdj329t7r",

3
  "status": "PENDING",

4
  "statusUrl": "/preview/CohortOperations/cmp_operation_01h9d8r0vte3hz8tykdj329t7r",

5
  "createdAt": "2026-01-15T10:00:00Z"

6
}

Poll the operation

poll-the-operation page anchor

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

1
curl -X GET 'https://audiences.twilio.com/preview/CohortOperations/cmp_operation_01h9d8r0vte3hz8tykdj329t7r' \

2
-u $TWILIO_API_KEY:$TWILIO_API_SECRET

Sample response:

1
{

2
  "operationId": "cmp_operation_01h9d8r0vte3hz8tykdj329t7r",

3
  "status": "COMPLETED",

4
  "statusUrl": "/preview/CohortOperations/cmp_operation_01h9d8r0vte3hz8tykdj329t7r",

5
  "createdAt": "2026-01-15T10:00:00Z",

6
  "completedAt": "2026-01-15T10:00:04Z",

7
  "resultUrl": "/preview/CohortSnapshots/cmp_cohortsnapshot_01h9d8r0vte3hz8tykdj329t7r",

8
  "result": {

9
    "cohortSnapshotId": "cmp_cohortsnapshot_01h9d8r0vte3hz8tykdj329t7r",

10
    "profileCount": 15420

11
  }

12
}

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

To learn more, see Operations.

Retrieve matching profiles

retrieve-matching-profiles page anchor

Pass the cohortSnapshotId to page through the matching customer profiles.

1
curl -X GET 'https://audiences.twilio.com/preview/CohortSnapshots/cmp_cohortsnapshot_01h9d8r0vte3hz8tykdj329t7r/Profiles' \

2
-u $TWILIO_API_KEY:$TWILIO_API_SECRET

Sample response:

1
{

2
  "profiles": [

3
    {

4
      "profileId": "mem_profile_01h9d8r0vte3hz8tykdj329t7r",

5
      "variables": {

6
        "email": "jane@example.com"

7
      }

8
    }

9
  ],

10
  "meta": {

11
    "key": "profiles",

12
    "pageSize": 50,

13
    "nextToken": "eyJvZmZzZXQiOjUwfQ"

14
  }

15
}

If your snapshot matches more profiles than fit on a single page, see Retrieving profiles for details on handling pagination tokens and parallel execution.

Next steps

next-steps page anchor