Fetch a cohort definition by ID

(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/{cohortId}

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

Retrieves a specific cohort definition by its ID.

Conditional Requests

Supports If-None-Match; returns 304 Not Modified when the ETag matches.

Request

Authentication

Basic Auth

Headers

Property nameTypeRequiredDescription

If-None-Matchstring

Optional

Used for conditional requests. If the ETag matches, the server returns 304 Not Modified, reducing bandwidth and improving performance.

Max length: 100

Path parameters

Property nameTypeRequiredDescription

cohortIdstring

required

The cohortId identifier

Responses

200304401403404429500

OK - Cohort retrieved successfully

SchemaExample

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

labelsobject

Optional

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

Maximum of 10 key-value pairs
Maximum size of a label key is 128 characters
Maximum size of a label 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. Labels are echoed back in the labels 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 labels 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

Fetch a cohort definition by ID

1curl -X GET "https://audiences.twilio.com/preview/Cohorts/cohortId" \
2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Response

1{
2  "id": "cmp_cohort_01h9d8r0vte3hz8tykdj329t7r",
3  "displayName": "Active US Adults",
4  "description": "US-based adults aged 18 and older who have an email address",
5  "storeType": "TWILIO",
6  "storeId": "mem_store_01h9d8r0vte3hz8tykdj329t7r",
7  "criteria": "profile.trait.Contact.age >= 18 && profile.trait.Contact.country == \"US\" && has(profile.address.email)",
8  "labels": {
9    "environment": "production",
10    "campaign": "q1-2026"
11  },
12  "createdAt": "2026-01-15T10:00:00Z",
13  "updatedAt": "2026-01-15T10:00:00Z"
14}