Create a cohort snapshot

(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.

POST/preview/CohortSnapshots

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

Creates a cohort snapshot of profiles with variables. The source field determines the source of profiles:

COHORT Source: References an existing cohort by ID.

STORE Source: Directly queries a profile store with inline criteria.

Workflow

Create a snapshot using this endpoint
Poll CohortOperations to check when processing completes
Use FetchCohortSnapshot to retrieve metadata
Use ListCohortSnapshotProfiles to retrieve paginated profile data

Rate Limiting

Rate-limited to 5 requests per minute and 100 requests per day per account.

Request

Authentication

Basic Auth

Headers

Property nameTypeRequiredDescription

Idempotency-Keystring

Optional

Client-provided idempotency key for safe request retries.

When provided, the server ensures that duplicate requests with the same key produce the same result without executing the operation multiple times.

Requirements:

Must be a non-empty string (max 128 characters)
Keys are retained for at least 24 hours
Scope: Account + Region combination
If a different payload is sent with the same key, returns 422 Unprocessable Content

If a request is replayed with the same idempotency key, the response will include the header Idempotent-Replayed: true.

Min length: 1Max length: 128

Request body

Encoding type:application/json

SchemaExample

Property nameTypeRequiredDescriptionChild properties

source

oneOf:

required

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

variablesarray[object]

Optional

CEL projection expressions specifying what data to include for each profile in the cohort snapshot. See the Audiences CEL Specification section for full syntax reference.

Example:

[{"expression":"profile.address.email","displayName":"email"},{"expression":"profile.trait.Contact.firstName","displayName":"first_name"}]

Min items: 0Max items: 50

Show variables properties

partitionCountOverrideinteger

Optional

Optional override for the number of partitions (up to 500). If not provided, the system automatically determines the optimal number.

Example: 4Minimum: 1Maximum: 500

profilesExpiresAtstring<date-time>

Optional

When the cohort snapshot's profile data expires. Must be within 30 days of creation. Defaults to 7 days if not specified.

Example: 2026-02-14T00:00:00Z

profileLimitinteger

Optional

Maximum number of profiles to include in the cohort snapshot.

Example: 50Minimum: 1Maximum: 50

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

Responses

202400401403404422429500

Accepted - Operation accepted for asynchronous processing. Poll the CohortOperations endpoint to check status.

SchemaExample

Property nameTypeRequiredDescriptionChild properties

operationIdstring

read-only

Optional

Unique identifier for the operation following TTID format. Format: cmp_operation_{uuidv7-encoded}

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

statusenum<string>

read-only

Optional

Current status of the operation.

PENDING: Operation is waiting to be processed
RUNNING: Operation is in progress
COMPLETED: Operation finished successfully
FAILED: Operation failed (check error field)
CANCELLED: Operation was cancelled by the user

Example: RUNNINGPossible values:

PENDINGRUNNINGCOMPLETEDFAILEDCANCELLED

statusUrlstring<uri-reference>

read-only

Optional

URL to poll for operation status

Example: /preview/CohortOperations/cmp_operation_01h9d8r0vte3hz8tykdj329t7rMax length: 500

createdAtstring<date-time>

read-only

Optional

Timestamp when the operation was created

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

completedAtstring<date-time>

read-only

Optional

Timestamp when the operation completed (present for terminal states)

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

payloadobject

read-only

Optional

Operation-specific metadata and progress information for a Cohort operation.

Show payload properties

resultUrlstring<uri-reference>

read-only

Optional

URL of the resulting resource. Present when status is COMPLETED and the operation produced or modified a resource.

Not present for deletion operations (DELETE, SNAPSHOT_DELETE) since the resource no longer exists after completion.

Example: /preview/CohortSnapshots/cmp_cohortsnapshot_01h9d8r0vte3hz8tykdj329t7rMax length: 500

resultobject

read-only

Optional

Operation-specific output data. Only present when status is COMPLETED. Fields present depend on operationType:

SNAPSHOT: cohortSnapshotId, cohortId (COHORT-sourced only), profileCount, partitionCount, updatedAt
SNAPSHOT_DELETE: cohortSnapshotId, cohortId (COHORT-sourced only)
UPDATE: cohortId, updatedAt
DELETE: cohortId

Show result properties

errorobject

read-only

Optional

Detailed error information following RFC 9457 Problem Details standard. Only present when status is FAILED.

Show error properties

Request examples

Create a cohort snapshot

1CREATE_COHORT_SNAPSHOT_REQUEST_OBJ=$(cat << EOF
2{
3  "source": {
4    "cohortId": "cmp_cohort_01h9d8r0vte3hz8tykdj329t7r"
5  },
6  "variables": [
7    {
8      "expression": "profile.address.email",
9      "displayName": "email"
10    },
11    {
12      "expression": "profile.trait.Contact.firstName",
13      "displayName": "first_name"
14    }
15  ]
16}
17EOF
18)
19curl -X POST "https://audiences.twilio.com/preview/CohortSnapshots" \
20--json "$CREATE_COHORT_SNAPSHOT_REQUEST_OBJ" \
21-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Response

1{
2  "operationId": "cmp_operation_01h9d8r0vte3hz8tykdj329t7r",
3  "status": "PENDING",
4  "statusUrl": "/preview/CohortOperations/cmp_operation_01h9d8r0vte3hz8tykdj329t7r",
5  "createdAt": "2026-01-15T10:00:00Z"
6}