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 tags to filter by tags (format: key1:value1,key2:value2)
Use cohortId to filter COHORT-sourced snapshots for a specific cohort
Use storeId to filter snapshots for a specific store. It returns both STORE-sourced snapshots and COHORT-sourced snapshots whose cohort is in that store

Ordering

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

Pagination

Token-based pagination via pageSize and pageToken.

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

storeIdstring

Optional

Filter to cohort snapshots for a specific store. Returns both STORE-sourced snapshots and COHORT-sourced snapshots whose cohort is in that store.

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

tagsobject

read-only

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 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_API_KEY:$TWILIO_API_SECRET

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      "tags": {
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}