---
"@context": https://schema.org
"@type": TechArticle
"@id": https://www.twilio.com/docs/cohorts/concepts/retrieving-profiles#article
headline: Retrieving profiles
description: Learn how to page through the profiles in a Twilio Cohorts snapshot, including large snapshots that span multiple partitions.
url: https://www.twilio.com/docs/cohorts/concepts/retrieving-profiles
inLanguage: en
dateModified: 2026-10-01T16:19:20.000Z
author:
  "@type": Organization
  name: Twilio Developer Education Team
publisher:
  "@type": Organization
  name: Twilio
---

# Retrieving profiles

## Paging through profiles

After a snapshot operation completes, you can retrieve its matching profiles from the Snapshot Profiles endpoint.

```bash
curl -X GET 'https://audiences.twilio.com/preview/CohortSnapshots/cmp_cohortsnapshot_01h9d8r0vte3hz8tykdj329t7r/Profiles' \
-u $TWILIO_API_KEY:$TWILIO_API_SECRET
```

Each profile entry includes a `profileId` and a `variables` object that contains the data fields you projected when you created the snapshot. If you omitted `variables` during creation, only `profileId` is returned.

```json
{
  "profiles": [
    {
      "profileId": "mem_profile_01h9d8r0vte3hz8tykdj329t7r",
      "variables": {
        "email": "jane@example.com"
      }
    }
  ],
  "meta": {
    "key": "profiles",
    "pageSize": 50,
    "nextToken": "eyJvZmZzZXQiOjUwfQ"
  }
}
```

The `meta.nextToken` field appears whenever additional pages remain. Pass its value back as the `pageToken` query parameter to fetch the next page. Continue this process until `nextToken` is no longer present in the response.

## Large snapshots and parallel processing

For snapshots that match many profiles, Twilio splits the results across multiple partitions so that you can retrieve them with parallel worker threads.

First, request the snapshot resource to determine its `partitionCount`.

```bash
curl -X GET 'https://audiences.twilio.com/preview/CohortSnapshots/cmp_cohortsnapshot_01h9d8r0vte3hz8tykdj329t7r' \
-u $TWILIO_API_KEY:$TWILIO_API_SECRET
```

**Sample response**:

```json
{
  "cohortSnapshotId": "cmp_cohortsnapshot_01h9d8r0vte3hz8tykdj329t7r",
  "partitionCount": 4,
  "profileCount": 42000,
  "labels": {
    "key": "value"
  }
}
```

Then request each partition independently by using the `partition` query parameter:

```bash
curl -X GET 'https://audiences.twilio.com/preview/CohortSnapshots/cmp_cohortsnapshot_01h9d8r0vte3hz8tykdj329t7r/Profiles?partition=0' \
-u $TWILIO_API_KEY:$TWILIO_API_SECRET
```

By default, Cohorts calculates the optimal `partitionCount` based on the snapshot's total profile volume.

> \[!NOTE]
>
> If your downstream processing architecture requires a specific thread count or chunk size, you can pass `partitionCountOverride` (up to 500) when you call Create Snapshot. You can also pass `profileLimit` if you want to retrieve only a capped sample of matching profiles.

### Partitioning rules

* **Zero-based indexing**: Partition indices are zero-based, ranging from `0` through `partitionCount - 1`. Passing an index outside this range returns HTTP `400 Bad Request`.
* **Independent pagination**: Each partition paginates independently by using `pageToken` until its own `nextToken` field is absent.
* **No duplicate profiles**: Retrieving partitions in parallel is thread-safe and ensures that no profile appears in more than one partition.
* **Empty partitions**: When you set the `partitionCountOverride` parameter, some partitions might not contain any profiles. This happens when you request more partitions than there are matching profiles to distribute. For example, if you set `partitionCountOverride` to 500 and the snapshot contains 10 profiles, most partitions are empty. If you request one of these partitions, the response includes an empty profiles array (`"profiles": []`). Consider the partition complete and proceed to the next partition.

## Next steps

* See the [Cohorts API reference](/docs/api/audiences/preview).
* Learn about [Rate limits](/docs/cohorts/api/rate-limits).