List cohort snapshots

(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/CohortSnapshots

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

Retrieves a paginated list of cohort snapshots.

Filtering

Use labels to filter by labels (format: key1:value1,key2:value2)
Use cohortId to filter COHORT-sourced snapshots for a specific cohort
Use storeId to filter STORE-sourced snapshots for a specific store

Ordering

Use orderBy (CREATED_AT or COMPLETED_AT) and orderDirection (ASC or DESC). Default: CREATED_AT DESC.

Pagination

Token-based pagination via pageSize and pageToken.

Request

Authentication

Basic Auth

Query string

Property nameTypeRequiredDescription

labelsstring

Optional

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

Format: key1:value1,key2:value2

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

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

Reserved (twilio__) label 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._~-]+)*$

storeIdstring

Optional

Filter to cohort snapshots for a specific store (STORE-sourced only)

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

cohortIdstring

Optional

Filter to cohort snapshots for a specific cohort (COHORT-sourced only)

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

orderByenum<string>

Optional

Field to order results by

Default: CREATED_ATPossible values:

CREATED_ATCOMPLETED_AT

orderDirectionenum<string>

Optional

Sort direction for results

Default: DESCPossible values:

ASCDESC

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

200400401403404429500

OK - List of cohort snapshots

SchemaExample

Property nameTypeRequiredDescriptionChild properties

cohortSnapshotsarray[object]

Optional

List of cohort snapshots

Max items: 100

Show cohortSnapshots properties

Property nameTypeRequiredDescriptionChild properties

cohortSnapshotIdstring

read-only

Optional

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

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

source

oneOf:

read-only

Optional

Defines the source of profiles for this cohort snapshot.

COHORT: References an existing cohort by ID
STORE: Directly queries a store with inline criteria

Show source properties

profileCountinteger

read-only

Optional

Total number of profiles in the cohort snapshot

Example: 15420Minimum: 0

partitionCountinteger

Optional

Number of partitions the cohort snapshot is split into, between 1 and 500. Unless overridden via partitionCountOverride, the system automatically determines the optimal number.

Example: 4Minimum: 1Maximum: 500

variablesarray[object]

read-only

Optional

Variable expressions included for each profile in the cohort snapshot.

Show variables properties

labelsobject

read-only

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 snapshot was created

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

completedAtstring<date-time>

read-only

Optional

Timestamp when the cohort snapshot completed

Example: 2026-01-15T10:03:45Z

profilesExpiresAtstring<date-time>

Optional

When the cohort snapshot's profile data expires. After this time, profile data is permanently deleted and ListCohortSnapshotProfiles returns a 404. The snapshot metadata remains retrievable via FetchCohortSnapshot.

Maximum 30 days from creation. Defaults to 7 days.

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

metaobject

Optional

Pagination metadata for list responses

Show meta properties

List cohort snapshots

1curl -X GET "https://audiences.twilio.com/preview/CohortSnapshots?orderBy=CREATED_AT&orderDirection=DESC&PageSize=20" \
2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Response

1{
2  "cohortSnapshots": [
3    {
4      "cohortSnapshotId": "cmp_cohortsnapshot_01h9d8r0vte3hz8tykdj329t7r",
5      "source": {
6        "cohortId": "cmp_cohort_01h9d8r0vte3hz8tykdj329t7r"
7      },
8      "profileCount": 15420,
9      "partitionCount": 4,
10      "variables": [
11        {
12          "expression": "profile.address.email",
13          "displayName": "email"
14        },
15        {
16          "expression": "profile.trait.Contact.firstName",
17          "displayName": "first_name"
18        }
19      ],
20      "labels": {
21        "environment": "production"
22      },
23      "createdAt": "2026-01-15T10:00:00Z",
24      "completedAt": "2026-01-15T10:03:45Z",
25      "profilesExpiresAt": "2026-01-22T10:00:00Z"
26    }
27  ],
28  "meta": {
29    "key": "cohortSnapshots",
30    "pageSize": 1
31  }
32}