Fetch a cohort snapshot 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/CohortSnapshots/{cohortSnapshotId}

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

Retrieves cohort snapshot metadata by its ID.

Works for snapshots from any source (COHORT or STORE).

Use ListCohortSnapshotProfiles to retrieve paginated profile data.

Request

Authentication

Basic Auth

Path parameters

Property nameTypeRequiredDescription

cohortSnapshotIdstring

required

The cohortSnapshotId identifier

Responses

200401403404429500

OK - Cohort snapshot metadata retrieved

SchemaExample

Property nameTypeRequiredDescriptionChild properties

cohortSnapshotobject

Optional

Represents an immutable point-in-time snapshot of cohort profiles with variable data.

The snapshot's source field determines the source of profiles:

COHORT source: Profiles from an existing cohort definition
STORE source: Profiles directly from a store using inline criteria

Show cohortSnapshot 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

Fetch a cohort snapshot by ID

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

Response

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