List cohort definitions

(new)

Beta

Twilio Cohorts is currently available as a Private Beta product and the information contained in this document is subject to change. You acknowledge and agree that your use of Twilio Cohorts is subject to the terms of the Services in Private Beta. This means that some features are not yet implemented and others may be changed before the product is declared as Generally Available. Private Beta products are not covered by the Twilio Support Terms or Twilio Service Level Agreement.

(warning)

Not a HIPAA Eligible Service or PCI Compliant

Twilio Cohorts is not a HIPAA Eligible Service or PCI compliant and should not be enabled in workflows that are subject to HIPAA or PCI.

GET/preview/Cohorts

Base url: https://audiences.twilio.com (base url)

Retrieves a list of cohort definitions with optional filtering.

Filtering

All filters are optional and combine with AND logic.

By Tags

Use tags to filter by one or many tags. Format: key1:value1,key2:value2

By Store

Use storeType and storeId together to filter cohorts by their profile store.

Ordering

Results are ordered by creation time, newest first (CREATED_AT, descending).

Pagination

Token-based pagination via pageSize and pageToken (see meta.nextToken).

Request

Authentication

Basic Auth

Query string

Property nameTypeRequiredDescription

tagsstring

Optional

Match resources by one or many tags. If more than one tag is specified in the query, the search returns resources that have all the tags (AND logic).

Format: key1:value1,key2:value2

Example: tags=environment:production,campaign:q1-2026

Filter character set: tag keys and values must match [a-zA-Z0-9._~-]+ (URL-safe unreserved characters). This is the same character set enforced when tags are written, so every tag that can be stored on a resource can also be filtered on here.

Reserved (twilio__) tag keys are rejected; filter on those through their dedicated query parameters (e.g. storeType/storeId) instead.

Pattern: ^[a-zA-Z0-9._~-]+:[a-zA-Z0-9._~-]+(,[a-zA-Z0-9._~-]+:[a-zA-Z0-9._~-]+)*$

storeTypeenum<string>

Optional

Filter by profile store type. Must be used together with storeId.

Example: TWILIOPossible values:

TWILIO

storeIdstring

Optional

Filter by profile store ID. Must be used together with storeType.

Example: mem_store_01h9d8r0vte3hz8tykdj329t7rPattern: ^mem_store_[a-zA-Z0-9]{26}$Min length: 36Max length: 36

pageSizeinteger

Optional

Maximum number of items to return in a single response. Must be between 1 and 100. Defaults to 20 when omitted.

Default: 20Minimum: 1Maximum: 100

pageTokenstring

Optional

An opaque, URL-safe cursor identifying the page of results to return. Pass back the meta.nextToken value from the previous response. If omitted, the API returns the first page of results.

The token's encoding and contents are an implementation detail and may change without notice, so do not decode, construct or modify one -- a malformed token is rejected. Carry it through unchanged.

Max length: 500

Responses

200400401403429500

OK - List of cohort definitions

Schema

Property nameTypeRequiredDescriptionChild properties

cohortsarray[object]

Optional

List of cohort definitions

Max items: 100

Show cohorts properties

Property nameTypeRequiredDescriptionChild properties

idstring

read-only

Optional

Unique identifier for the cohort following TTID format. Format: cmp_cohort_{uuidv7-encoded}

Example: cmp_cohort_01h9d8r0vte3hz8tykdj329t7rPattern: ^cmp_cohort_[a-zA-Z0-9]{26}$Max length: 100

displayNamestring

Optional

Human-readable name for the cohort

Example: Active US AdultsMin length: 1Max length: 255

descriptionstring

Optional

Optional description of the cohort

Example: US-based adults aged 18 and older who have an email addressMax length: 1000

storeIdstring

Optional

Unique identifier for the profile store

Example: mem_store_01h9d8r0vte3hz8tykdj329t7rPattern: ^mem_store_[a-zA-Z0-9]{26}$Min length: 36Max length: 36

storeTypeenum<string>

Optional

Type of profile store

Example: TWILIOPossible values:

TWILIO

criteriastring

Optional

A Boolean CEL (Common Expression Language) expression used to filter and select profiles.

Example: profile.trait.Contact.age >= 18 && profile.trait.Contact.country == "US" && has(profile.address.email)Max length: 2000

tagsobject

Optional

Tags for organizing and categorizing resources as key-value pairs.

Maximum of 10 key-value pairs
Maximum size of a tag key is 128 characters
Maximum size of a tag value is 256 characters
Keys and values must be non-empty and URL-safe: only unreserved characters (A-Z, a-z, 0-9, -, ., _, ~) are allowed. Tags are echoed back in the tags query parameter of the list endpoints, so anything you can store here can also be filtered on.
Keys cannot use the reserved twilio__ prefix

Example: {"environment":"production","campaign":"q1-2026"}Max properties: 10

Show tags properties

createdAtstring<date-time>

read-only

Optional

Timestamp when the cohort was created

Example: 2026-01-15T10:00:00Z

updatedAtstring<date-time>

read-only

Optional

Timestamp when the cohort was last updated

Example: 2026-01-15T10:00:00Z

metaobject

Optional

Pagination metadata for list responses

Show meta properties

List cohort definitions

1curl -X GET "https://audiences.twilio.com/preview/Cohorts?PageSize=20" \
2-u $TWILIO_API_KEY:$TWILIO_API_SECRET

Response

1{
2  "cohorts": [
3    {
4      "id": "cmp_cohort_01h9d8r0vte3hz8tykdj329t7r",
5      "displayName": "Active US Adults",
6      "description": "US-based adults aged 18 and older who have an email address",
7      "storeId": "mem_store_01h9d8r0vte3hz8tykdj329t7r",
8      "storeType": "TWILIO",
9      "criteria": "profile.trait.Contact.age >= 18 && profile.trait.Contact.country == \"US\" && has(profile.address.email)",
10      "tags": {
11        "environment": "production",
12        "campaign": "q1-2026"
13      },
14      "createdAt": "2026-01-15T10:00:00Z",
15      "updatedAt": "2026-01-15T10:00:00Z"
16    }
17  ],
18  "meta": {
19    "key": "cohorts",
20    "pageSize": 1,
21    "previousToken": "previousToken",
22    "nextToken": "nextToken"
23  }
24}