---
"@context": https://schema.org
"@type": TechArticle
"@id": https://www.twilio.com/docs/cohorts/cel/overview#article
headline: Writing filter criteria
description: Learn the basics of writing filter criteria for Twilio Cohorts, including profile traits, addresses, and data types.
url: https://www.twilio.com/docs/cohorts/cel/overview
inLanguage: en
dateModified: 2026-09-15T09:58:28.000Z
author:
  "@type": Organization
  name: Twilio Developer Education Team
publisher:
  "@type": Organization
  name: Twilio
---

# Writing filter criteria

## Overview

Twilio Cohorts uses the [Common Expression Language (CEL)](https://cel.dev) to define filter criteria for audience targeting. Each criterion evaluates to `true` or `false` for every profile in your connected store. Profiles for which the criterion evaluates to `true` are added to the resulting cohort snapshot.

Filter criteria can reference two profile properties: traits and addresses.

## Target by trait

Traits describe attributes attached to a profile, such as account tier, lifetime value, or sign-up date. Reference a trait by using `profile.trait.{traitGroup}.{traitName}`.

```txt
profile.trait.Account.status == "active"
```

Traits are typed as `string`, `integer`, `float`, `boolean`, `timestamp`, or `duration`. Array-typed traits aren't supported.

> \[!NOTE]
>
> `{traitGroup}` and `{traitName}` must exist in your connected store's schema. If either value isn't defined, the request is rejected as invalid.

## Target by address

Addresses represent contact channels attached to a profile, such as email addresses or phone numbers. Reference an address as `profile.address.{channel}`, where `channel` is `email`, `phone`, `whatsapp`, or `chat`.

Unlike traits, an address always returns a list of strings because a profile can have more than one address on the same channel (for example, two email addresses). You can't compare an address directly to a string. Instead, check for presence with `has()`, membership with `in`, or use list operations such as `.exists()`.

```txt
"jane@example.com" in profile.address.email
```

## Combine conditions

Combine multiple conditions with logical operators:

```txt
profile.trait.Account.status == "active" && profile.trait.Account.country == "US"
```

For details on how operators are evaluated, see [Operators and precedence](/docs/cohorts/cel/operators-and-precedence).

## Escape special characters in trait names

Trait group and field names that contain periods, dashes, double underscores, or that start with a digit must be escaped before you reference them in filter criteria. See [Escaping special characters](/docs/cohorts/cel/escaping-special-characters) for the complete list of escape sequences.

## Handle missing data

If a trait is absent on a profile, any comparison against it evaluates to `false`, which excludes the profile rather than raising an error. Use `has()` to check explicitly whether a trait is present. See [Null handling](/docs/cohorts/cel/null-handling) for more information.

## Type matching

Both sides of a comparison must be the same data type. For example, comparing a string-typed trait to an integer literal triggers a validation error when you create or update a cohort. See [Type matching](/docs/cohorts/cel/type-matching) for the full rules and available type-conversion functions.

## Expression limits

Twilio Cohorts enforces the following limits on CEL expressions:

| Limit                              | Value                             |
| ---------------------------------- | --------------------------------- |
| Maximum nesting depth              | 6 levels of parenthesized nesting |
| Maximum criteria length            | 10,000 characters                 |
| Maximum variable expression length | 500 characters                    |
| Maximum variables per snapshot     | 50                                |

Expressions that exceed these limits are rejected with an HTTP `422 Unprocessable Content` error.

## Next steps

* Learn about [operators and precedence](/docs/cohorts/cel/operators-and-precedence).
* Browse the available [functions](/docs/cohorts/cel/functions).
* Review [example criteria](/docs/cohorts/cel/common-filtering-patterns) for common filtering patterns.