---
"@context": https://schema.org
"@type": TechArticle
"@id": https://www.twilio.com/docs/cohorts/concepts/tags#article
headline: Tags
description: Learn how to use tags to organize and categorize Cohorts and Snapshots, and how to filter lists by tag.
url: https://www.twilio.com/docs/cohorts/concepts/tags
inLanguage: en
dateModified: 2026-10-23T18:21:16.000Z
author:
  "@type": Organization
  name: Twilio Developer Education Team
publisher:
  "@type": Organization
  name: Twilio
---

# Tags

## About tags

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

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

Tags are supported on Cohorts and Snapshots. Operations do not support tags.

## Set tags

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

The following constraints apply to tags:

* A resource can contain up to 10 tag 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 (`-`).
* Tag values must not be empty strings.
* Tag keys must not begin with the `twilio__` prefix, which is reserved.
* If you omit `tags` when you create a resource, the field is returned as `null` in API responses.
* To remove a tag from a Cohort, set its value to `null` in an update request.

## Filtering by tags

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

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

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

```bash
curl -X GET 'https://audiences.twilio.com/preview/Cohorts?tags=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).