Fetch a cohort snapshot by ID
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.
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.
Basic authentication is an authentication scheme built into the HTTP protocol.
To use it, send your HTTP requests with an Authorization header that contains the word "Basic"
followed by a space and a base64-encoded string of accountSid:authToken.
Example: Authorization: Basic ZGVtbzpwQDU1dzByZA==
The cohortSnapshotId identifier
OK - Cohort snapshot metadata retrieved
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
Optional
Unique identifier for the cohort snapshot following TTID format.
Format: cmp_cohortsnapshot_{uuidv7-encoded}
cmp_cohortsnapshot_01h9d8r0vte3hz8tykdj329t7rPattern: ^cmp_cohortsnapshot_[a-zA-Z0-9]{26}$Max length: 100Optional
Defines the source of profiles for this cohort snapshot.
- COHORT: References an existing cohort by ID
- STORE: Directly queries a store with inline criteria
Optional
Unique identifier for the cohort following TTID format.
Format: cmp_cohort_{uuidv7-encoded}
cmp_cohort_01h9d8r0vte3hz8tykdj329t7rPattern: ^cmp_cohort_[a-zA-Z0-9]{26}$Max length: 100Optional
Total number of profiles in the cohort snapshot
15420Minimum: 0Optional
Number of partitions the cohort snapshot is split into, between 1 and 500. Unless overridden via partitionCountOverride, the system automatically determines the optimal number.
4Minimum: 1Maximum: 500Optional
Variable expressions included for each profile in the cohort snapshot.
Optional
The CEL expression.
500Optional
Human-readable display name for this variable. Must start with a letter or underscore, followed by letters, digits, underscores, or dots. Any casing or separator style is accepted, so camelCase, snake_case and dot.delimited all work. The response always uses the exact name you submitted. Two variables in the same request may not use the identical displayName string.
^[A-Za-z_][A-Za-z0-9_.]*$Max length: 255Optional
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 thetagsquery parameter of the list endpoints, so anything you can store here can also be filtered on. - Keys cannot use the reserved
twilio__prefix
{"environment":"production","campaign":"q1-2026"}Max properties: 10Optional
Timestamp when the cohort snapshot was created
2026-01-15T10:00:00ZOptional
Timestamp when the cohort snapshot completed
2026-01-15T10:03:45ZOptional
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.
2026-01-22T10:00:00Z{"cohortSnapshot": {"cohortSnapshotId": "cmp_cohortsnapshot_01h9d8r0vte3hz8tykdj329t7r","source": {"cohortId": "cmp_cohort_01h9d8r0vte3hz8tykdj329t7r"},"profileCount": 15420,"partitionCount": 4,"variables": [{"expression": "profile.address.email","displayName": "email"},{"expression": "profile.trait.Contact.firstName","displayName": "first_name"}],"tags": {"environment": "production"},"createdAt": "2026-01-15T10:00:00Z","completedAt": "2026-01-15T10:03:45Z","profilesExpiresAt": "2026-01-22T10:00:00Z"}}
Bad Request - The request was invalid or cannot be processed.
Request-schema failures list every failing field in errors[]. Criteria and variable expressions are checked after that, one at a time: the first invalid expression is reported in detail, with no errors[]. Query-parameter checks the schema cannot express, such as storeType without storeId, return 24001 with no errors[].
Optional
A URI reference (RFC3986) that identifies the problem type. For Twilio
errors, this is always https://www.twilio.com/docs/api/errors/{code}.
https://www.twilio.com/docs/api/errors/24000Max length: 500Optional
A short, human-readable summary of the problem type. SHOULD NOT change from occurrence to occurrence except for purposes of localization.
Invalid parameter valueMin length: 16Max length: 128Optional
The HTTP status code generated by the origin server for this occurrence of the problem. MUST match the HTTP status code returned in the response.
400Optional
Twilio-specific error code (extension member per RFC-9457 Section 3.2). Numeric code uniquely identifying the error type within Twilio's error taxonomy. Registered at https://www.twilio.com/docs/api/errors.
24000Optional
A human-readable explanation specific to this occurrence of the problem. May vary between occurrences of the same problem type.
The 'name' parameter is required but was not provided.Min length: 16Max length: 1024Optional
A URI reference identifying the specific occurrence of the problem; typically the request path.
/preview/Cohorts/cmp_cohort_01h9d8r0vte3hz8tykdj329t7rMax length: 500Optional
Array of field-level errors for HTTP 400/422 responses. Each entry identifies a single failure with a JSON Pointer to its location.
When more than 50 field errors would be emitted, the array is truncated to 50 entries and the 50th entry's detail describes the truncation.
[{"detail":"displayName is required and must be a non-empty value","pointer":"#/displayName"},{"detail":"criteria is required and must be a non-empty value","pointer":"#/criteria"}]Max items: 50Optional
A human-readable explanation of this field-level error.
displayName is required and must be a non-empty valueMin length: 16Max length: 1024Optional
RFC 6901 JSON Pointer to the location of the error. This API uses these prefixes:
- Request body field:
#/<field> - Query parameter:
#/query/<name> - Path parameter:
#/path/<name> - Request header:
#/headers/<name> - Root / unknown: #/ Array indices use digits (e.g. #/tags/0/key). Property names containing '~' or '/' are escaped per RFC 6901 (~0 and ~1).
#/displayNameMax length: 500{"type": "https://www.twilio.com/docs/api/errors/24000","title": "Validation error","status": 400,"code": 24000,"detail": "Request failed validation. See errors[] for field-level details.","instance": "/preview/Cohorts","errors": [{"detail": "displayName is required and must be a non-empty value","pointer": "#/displayName"}]}
Unauthorized - Authentication credentials are missing or invalid
Optional
A URI reference (RFC3986) that identifies the problem type. For Twilio
errors, this is always https://www.twilio.com/docs/api/errors/{code}.
https://www.twilio.com/docs/api/errors/24000Max length: 500Optional
A short, human-readable summary of the problem type. SHOULD NOT change from occurrence to occurrence except for purposes of localization.
Invalid parameter valueMin length: 16Max length: 128Optional
The HTTP status code generated by the origin server for this occurrence of the problem. MUST match the HTTP status code returned in the response.
400Optional
Twilio-specific error code (extension member per RFC-9457 Section 3.2). Numeric code uniquely identifying the error type within Twilio's error taxonomy. Registered at https://www.twilio.com/docs/api/errors.
24000Optional
A human-readable explanation specific to this occurrence of the problem. May vary between occurrences of the same problem type.
The 'name' parameter is required but was not provided.Min length: 16Max length: 1024Optional
A URI reference identifying the specific occurrence of the problem; typically the request path.
/preview/Cohorts/cmp_cohort_01h9d8r0vte3hz8tykdj329t7rMax length: 500Optional
Array of field-level errors for HTTP 400/422 responses. Each entry identifies a single failure with a JSON Pointer to its location.
When more than 50 field errors would be emitted, the array is truncated to 50 entries and the 50th entry's detail describes the truncation.
[{"detail":"displayName is required and must be a non-empty value","pointer":"#/displayName"},{"detail":"criteria is required and must be a non-empty value","pointer":"#/criteria"}]Max items: 50Optional
A human-readable explanation of this field-level error.
displayName is required and must be a non-empty valueMin length: 16Max length: 1024Optional
RFC 6901 JSON Pointer to the location of the error. This API uses these prefixes:
- Request body field:
#/<field> - Query parameter:
#/query/<name> - Path parameter:
#/path/<name> - Request header:
#/headers/<name> - Root / unknown: #/ Array indices use digits (e.g. #/tags/0/key). Property names containing '~' or '/' are escaped per RFC 6901 (~0 and ~1).
#/displayNameMax length: 500{"type": "https://www.twilio.com/docs/api/errors/20003","title": "Authentication required","status": 401,"code": 20003,"detail": "The request requires valid authentication credentials.","instance": "/preview/Cohorts"}
Forbidden - The authenticated user does not have permission to access this resource
Optional
A URI reference (RFC3986) that identifies the problem type. For Twilio
errors, this is always https://www.twilio.com/docs/api/errors/{code}.
https://www.twilio.com/docs/api/errors/24000Max length: 500Optional
A short, human-readable summary of the problem type. SHOULD NOT change from occurrence to occurrence except for purposes of localization.
Invalid parameter valueMin length: 16Max length: 128Optional
The HTTP status code generated by the origin server for this occurrence of the problem. MUST match the HTTP status code returned in the response.
400Optional
Twilio-specific error code (extension member per RFC-9457 Section 3.2). Numeric code uniquely identifying the error type within Twilio's error taxonomy. Registered at https://www.twilio.com/docs/api/errors.
24000Optional
A human-readable explanation specific to this occurrence of the problem. May vary between occurrences of the same problem type.
The 'name' parameter is required but was not provided.Min length: 16Max length: 1024Optional
A URI reference identifying the specific occurrence of the problem; typically the request path.
/preview/Cohorts/cmp_cohort_01h9d8r0vte3hz8tykdj329t7rMax length: 500Optional
Array of field-level errors for HTTP 400/422 responses. Each entry identifies a single failure with a JSON Pointer to its location.
When more than 50 field errors would be emitted, the array is truncated to 50 entries and the 50th entry's detail describes the truncation.
[{"detail":"displayName is required and must be a non-empty value","pointer":"#/displayName"},{"detail":"criteria is required and must be a non-empty value","pointer":"#/criteria"}]Max items: 50Optional
A human-readable explanation of this field-level error.
displayName is required and must be a non-empty valueMin length: 16Max length: 1024Optional
RFC 6901 JSON Pointer to the location of the error. This API uses these prefixes:
- Request body field:
#/<field> - Query parameter:
#/query/<name> - Path parameter:
#/path/<name> - Request header:
#/headers/<name> - Root / unknown: #/ Array indices use digits (e.g. #/tags/0/key). Property names containing '~' or '/' are escaped per RFC 6901 (~0 and ~1).
#/displayNameMax length: 500{"type": "https://www.twilio.com/docs/api/errors/24003","title": "Access denied to this resource","status": 403,"code": 24003,"detail": "You do not have permission to access this resource.","instance": "/preview/Cohorts"}
Not Found - The requested resource does not exist
Optional
A URI reference (RFC3986) that identifies the problem type. For Twilio
errors, this is always https://www.twilio.com/docs/api/errors/{code}.
https://www.twilio.com/docs/api/errors/24000Max length: 500Optional
A short, human-readable summary of the problem type. SHOULD NOT change from occurrence to occurrence except for purposes of localization.
Invalid parameter valueMin length: 16Max length: 128Optional
The HTTP status code generated by the origin server for this occurrence of the problem. MUST match the HTTP status code returned in the response.
400Optional
Twilio-specific error code (extension member per RFC-9457 Section 3.2). Numeric code uniquely identifying the error type within Twilio's error taxonomy. Registered at https://www.twilio.com/docs/api/errors.
24000Optional
A human-readable explanation specific to this occurrence of the problem. May vary between occurrences of the same problem type.
The 'name' parameter is required but was not provided.Min length: 16Max length: 1024Optional
A URI reference identifying the specific occurrence of the problem; typically the request path.
/preview/Cohorts/cmp_cohort_01h9d8r0vte3hz8tykdj329t7rMax length: 500Optional
Array of field-level errors for HTTP 400/422 responses. Each entry identifies a single failure with a JSON Pointer to its location.
When more than 50 field errors would be emitted, the array is truncated to 50 entries and the 50th entry's detail describes the truncation.
[{"detail":"displayName is required and must be a non-empty value","pointer":"#/displayName"},{"detail":"criteria is required and must be a non-empty value","pointer":"#/criteria"}]Max items: 50Optional
A human-readable explanation of this field-level error.
displayName is required and must be a non-empty valueMin length: 16Max length: 1024Optional
RFC 6901 JSON Pointer to the location of the error. This API uses these prefixes:
- Request body field:
#/<field> - Query parameter:
#/query/<name> - Path parameter:
#/path/<name> - Request header:
#/headers/<name> - Root / unknown: #/ Array indices use digits (e.g. #/tags/0/key). Property names containing '~' or '/' are escaped per RFC 6901 (~0 and ~1).
#/displayNameMax length: 500{"type": "https://www.twilio.com/docs/api/errors/24004","title": "Resource not found","status": 404,"code": 24004,"detail": "Cohort with ID 'cmp_cohort_01h9d8r0vte3hz8tykdj329t7r' was not found.","instance": "/preview/Cohorts/cmp_cohort_01h9d8r0vte3hz8tykdj329t7r"}
Too Many Requests - Rate limit exceeded
Optional
A URI reference (RFC3986) that identifies the problem type. For Twilio
errors, this is always https://www.twilio.com/docs/api/errors/{code}.
https://www.twilio.com/docs/api/errors/24000Max length: 500Optional
A short, human-readable summary of the problem type. SHOULD NOT change from occurrence to occurrence except for purposes of localization.
Invalid parameter valueMin length: 16Max length: 128Optional
The HTTP status code generated by the origin server for this occurrence of the problem. MUST match the HTTP status code returned in the response.
400Optional
Twilio-specific error code (extension member per RFC-9457 Section 3.2). Numeric code uniquely identifying the error type within Twilio's error taxonomy. Registered at https://www.twilio.com/docs/api/errors.
24000Optional
A human-readable explanation specific to this occurrence of the problem. May vary between occurrences of the same problem type.
The 'name' parameter is required but was not provided.Min length: 16Max length: 1024Optional
A URI reference identifying the specific occurrence of the problem; typically the request path.
/preview/Cohorts/cmp_cohort_01h9d8r0vte3hz8tykdj329t7rMax length: 500Optional
Array of field-level errors for HTTP 400/422 responses. Each entry identifies a single failure with a JSON Pointer to its location.
When more than 50 field errors would be emitted, the array is truncated to 50 entries and the 50th entry's detail describes the truncation.
[{"detail":"displayName is required and must be a non-empty value","pointer":"#/displayName"},{"detail":"criteria is required and must be a non-empty value","pointer":"#/criteria"}]Max items: 50Optional
A human-readable explanation of this field-level error.
displayName is required and must be a non-empty valueMin length: 16Max length: 1024Optional
RFC 6901 JSON Pointer to the location of the error. This API uses these prefixes:
- Request body field:
#/<field> - Query parameter:
#/query/<name> - Path parameter:
#/path/<name> - Request header:
#/headers/<name> - Root / unknown: #/ Array indices use digits (e.g. #/tags/0/key). Property names containing '~' or '/' are escaped per RFC 6901 (~0 and ~1).
#/displayNameMax length: 500{"type": "https://www.twilio.com/docs/api/errors/20429","title": "Rate limit exceeded","status": 429,"code": 20429,"detail": "Too many requests. Please retry after 30 seconds.","instance": "/preview/Cohorts"}
Internal Server Error - An unexpected error occurred
Optional
A URI reference (RFC3986) that identifies the problem type. For Twilio
errors, this is always https://www.twilio.com/docs/api/errors/{code}.
https://www.twilio.com/docs/api/errors/24000Max length: 500Optional
A short, human-readable summary of the problem type. SHOULD NOT change from occurrence to occurrence except for purposes of localization.
Invalid parameter valueMin length: 16Max length: 128Optional
The HTTP status code generated by the origin server for this occurrence of the problem. MUST match the HTTP status code returned in the response.
400Optional
Twilio-specific error code (extension member per RFC-9457 Section 3.2). Numeric code uniquely identifying the error type within Twilio's error taxonomy. Registered at https://www.twilio.com/docs/api/errors.
24000Optional
A human-readable explanation specific to this occurrence of the problem. May vary between occurrences of the same problem type.
The 'name' parameter is required but was not provided.Min length: 16Max length: 1024Optional
A URI reference identifying the specific occurrence of the problem; typically the request path.
/preview/Cohorts/cmp_cohort_01h9d8r0vte3hz8tykdj329t7rMax length: 500Optional
Array of field-level errors for HTTP 400/422 responses. Each entry identifies a single failure with a JSON Pointer to its location.
When more than 50 field errors would be emitted, the array is truncated to 50 entries and the 50th entry's detail describes the truncation.
[{"detail":"displayName is required and must be a non-empty value","pointer":"#/displayName"},{"detail":"criteria is required and must be a non-empty value","pointer":"#/criteria"}]Max items: 50Optional
A human-readable explanation of this field-level error.
displayName is required and must be a non-empty valueMin length: 16Max length: 1024Optional
RFC 6901 JSON Pointer to the location of the error. This API uses these prefixes:
- Request body field:
#/<field> - Query parameter:
#/query/<name> - Path parameter:
#/path/<name> - Request header:
#/headers/<name> - Root / unknown: #/ Array indices use digits (e.g. #/tags/0/key). Property names containing '~' or '/' are escaped per RFC 6901 (~0 and ~1).
#/displayNameMax length: 500{"type": "https://www.twilio.com/docs/api/errors/20500","title": "Internal server error","status": 500,"code": 20500,"detail": "An unexpected error occurred while processing your request. Please try again later."}
1curl -X GET "https://audiences.twilio.com/preview/CohortSnapshots/cohortSnapshotId" \2-u $TWILIO_API_KEY:$TWILIO_API_SECRET
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"tags": {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}