Snapshots

A snapshot is an immutable, point-in-time list of the profiles that match a set of filter criteria. When you create a snapshot, Cohorts evaluates the criteria against your connected profile store and materializes the matching profiles so you can retrieve them or pass them to downstream APIs.

Creating a snapshot starts an asynchronous Operation. Poll the Operation until it completes, and then retrieve the snapshot's profiles.

You can generate a snapshot in either of the following ways.

Reference a cohort's ID in the source object. Cohorts resolves the cohort's saved criteria at the time you create the snapshot.

1
curl -X POST 'https://audiences.twilio.com/preview/CohortSnapshots' \
2
-H 'Content-Type: application/json' \
3
-d '{
4
    "source": {
5
        "cohortId": "cmp_cohort_01h9d8r0vte3hz8tykdj329t7r"
6
    },
7
    "labels": {
8
        "key": "value"
9
    }
10
}' \
11
-u $TWILIO_API_KEY:$TWILIO_API_SECRET

The optional labels object works the same way for either creation method described below.

Provide storeType, storeId, and criteria directly in the source object without saving a cohort first. Inline criteria are useful for ad-hoc audience checks, automated scripts, or exploratory testing.

1
curl -X POST 'https://audiences.twilio.com/preview/CohortSnapshots' \
2
-H 'Content-Type: application/json' \
3
-d '{
4
    "source": {
5
        "storeType": "TWILIO",
6
        "storeId": "mem_store_01h9d8r0vte3hz8tykdj329t7r",
7
        "criteria": "profile.trait.Account.status == \"active\""
8
    }
9
}' \
10
-u $TWILIO_API_KEY:$TWILIO_API_SECRET

Regardless of the method you choose, the snapshot captures the criteria at the moment of creation. Later updates to a cohort's saved criteria do not alter existing snapshots.

The Create Snapshot request accepts an optional Idempotency-Key header so you can safely retry a request without creating a duplicate snapshot. Generate a new key (for example, a UUID) for each distinct request, and reuse the same value only when retrying that exact request after a network failure or timeout. Idempotency keys are retained for at least 24 hours and are scoped to your account. A retry with the same key and an identical request body returns the original response, which includes an Idempotent-Replayed: true header. Reusing a key with a different request body fails with HTTP 422 Unprocessable Content.

By default, a snapshot's profile results include only the profile ID. To include profile traits or address details in the response, pass a variables array when you create the snapshot. Each variable projects a specific field into the result set, keyed by displayName.

1
"variables": [
2
  { "expression": "profile.address.email", "displayName": "email" },
3
  { "expression": "profile.trait.Account.firstName", "displayName": "firstName" }
4
]

A variable's expression can reference more than one trait or address field. It accepts any valid CEL expression, including arithmetic and string concatenation, for example:

1
"variables": [
2
  { "expression": "profile.trait.Account.lifetimeValue - profile.trait.Account.totalRefunds", "displayName": "netValue" },
3
  { "expression": "profile.trait.Contact.firstName + \" \" + profile.trait.Contact.lastName", "displayName": "fullName" }
4
]

You can also use the ternary operator (?:) to derive a value from a condition, and chain multiple ternary expressions to handle more than two possible results. Each false branch becomes another ternary, so the expression continues evaluating conditions until one returns true or the final default branch executes.

For example, the following variable projects "platinum" when lifetimeValue is greater than 10,000, "gold" when it is greater than 1,000, and "standard" for all other values.

1
"variables": [
2
  { "expression": "profile.trait.Account.lifetimeValue > 10000 ? \"platinum\" : profile.trait.Account.lifetimeValue > 1000 ? \"gold\" : \"standard\"", "displayName": "tier" }
3
]

See Common filtering patterns for more examples of valid CEL expressions.

You can project up to 50 variables in a single snapshot.

When you create a snapshot, you can pass optional parameters that control how the snapshot is computed and returned:

• profileLimit (integer, maximum 50): Sets a ceiling on the number of matching profiles included in the snapshot. Use this option for test sampling, quick previews, or to cap output size before you launch a full job.
• partitionCountOverride (integer, maximum 500): Manually sets the number of partitions generated for parallel fetching. If omitted, Cohorts calculates an optimal value based on your profile volume. When you specify a value, some partitions can be empty and return "profiles": []. For example, if you request 500 partitions and the snapshot contains 10 profiles, most partitions are empty. Learn more about how partitions work and how to fetch them in parallel.

1
curl -X POST 'https://audiences.twilio.com/preview/CohortSnapshots' \
2
-H 'Content-Type: application/json' \
3
-d '{
4
    "source": {
5
        "cohortId": "cmp_cohort_01h9d8r0vte3hz8tykdj329t7r"
6
    },
7
    "profileLimit": 50,
8
    "partitionCountOverride": 4
9
}' \
10
-u $TWILIO_API_KEY:$TWILIO_API_SECRET

Profile data in a snapshot expires after a configurable period, set with profilesExpiresAt when you create the snapshot. The default is 7 days; you can extend this period to a maximum of 30 days. After the data expires, requests to list the snapshot's profiles return 404 Not Found, but the snapshot's metadata, such as creation date and profile count, remains available.

Deleting a snapshot is processed asynchronously and removes it entirely, including its metadata. In contrast, profile expiration only deletes the profile data and keeps the metadata.

• Learn about Operations.
• Learn about Retrieving profiles from a snapshot.
• Learn about Labels.
• See the Cohorts API reference.