---
"@context": https://schema.org
"@type": TechArticle
"@id": https://www.twilio.com/docs/cohorts/concepts/labels#article
headline: Labels
description: Learn how to use labels to organize and categorize Cohorts and Snapshots, and how to filter lists by label.
url: https://www.twilio.com/docs/cohorts/concepts/labels
inLanguage: en
dateModified: 2026-09-15T09:58:28.000Z
author:
  "@type": Organization
  name: Twilio Developer Education Team
publisher:
  "@type": Organization
  name: Twilio
---

# Labels

## About labels

Labels are key-value pairs that you attach to a Cohort or Snapshot to organize and categorize those resources. Twilio Cohorts does not interpret label values; you can use them operationally, for example, to tag resources by team, environment, or campaign.

```json
"labels": {
    "team": "growth",
    "environment": "production"
}
```

Labels are supported on Cohorts and Snapshots. Operations do not support labels.

## Set labels

Pass a `labels` object when you create a Cohort or Snapshot. You can update a Cohort's labels later. A Snapshot's labels are fixed upon creation, just like the rest of its immutable data.

The following constraints apply to labels:

* A resource can contain up to 10 label key-value pairs.
* Keys can contain up to 128 characters; values can contain up to 256 characters.
* Allowed characters: letters, numbers, periods (`.`), underscores (`_`), tildes (`~`), and hyphens (`-`).
* Label values must not be empty strings.
* Label keys must not begin with the `twilio__` prefix, which is reserved.
* If you omit `labels` when you create a resource, the field is returned as `null` in API responses.
* To remove a label from a Cohort, set its value to `null` in an update request.

## Filtering by labels

Pass a `labels` query parameter to List Cohorts or List Snapshots (see the [Cohorts API reference](/docs/api/audiences/preview)) to filter results by one or more labels.

```txt
GET /preview/Cohorts?labels=team:growth,environment:production
```

Separate multiple labels with commas. When you specify more than one label, the results must match all of the specified criteria.

```bash
curl -X GET 'https://audiences.twilio.com/preview/Cohorts?labels=team:growth,environment:production' \
-u $TWILIO_API_KEY:$TWILIO_API_SECRET
```

## Next steps

* Learn about [Cohorts](/docs/cohorts/concepts/cohorts) and [Snapshots](/docs/cohorts/concepts/snapshots).
* See the [Cohorts API reference](/docs/api/audiences/preview).