Update a cohort definition

(new)

Beta

Twilio Cohorts is currently available as a Private Beta product and the information contained in this document is subject to change. You acknowledge and agree that your use of Twilio Cohorts is subject to the terms of the Services in Private Beta. This means that some features are not yet implemented and others may be changed before the product is declared as Generally Available. Private Beta products are not covered by the Twilio Support Terms or Twilio Service Level Agreement.

(warning)

Not a HIPAA Eligible Service or PCI Compliant

Twilio Cohorts is not a HIPAA Eligible Service or PCI compliant and should not be enabled in workflows that are subject to HIPAA or PCI.

PATCH/preview/Cohorts/{cohortId}

Base url: https://audiences.twilio.com (base url)

Initiates an update to an existing cohort definition.

Supports the optional If-Match header for optimistic concurrency (412 on mismatch).

Processed asynchronously: returns 202 Accepted with an Operation resource that can be polled via CohortOperations to track update progress.

Merge Patch Semantics

Uses JSON Merge Patch (RFC 7396). Only fields in the request body are updated; set a label value to null to remove it.

Updatable Fields

displayName
description
labels
criteria

Immutable Fields

storeType
storeId

Request

Authentication

Basic Auth

Headers

Property nameTypeRequiredDescription

If-Matchstring

Optional

Used for optimistic concurrency control on mutating requests (PATCH, PUT, DELETE). The value should be the ETag returned from a previous GET request for this resource.

If the current ETag does not match, the server returns 412 Precondition Failed, indicating the resource has been modified since it was last retrieved.

When omitted, the write proceeds without ETag validation.

Max length: 100

Path parameters

Property nameTypeRequiredDescription

cohortIdstring

required

The cohortId identifier

Request body

Encoding type:application/json

Schema

Property nameTypeRequiredDescriptionChild properties

displayNamestring

Optional

Human-readable name for the cohort

Example: Active US AdultsMin length: 1Max length: 255

descriptionstring

Optional

Optional description of the cohort

Example: US-based adults aged 18 and older who have an email addressMax length: 1000

criteriastring

Optional

A Boolean CEL (Common Expression Language) expression used to filter and select profiles.

Example: profile.trait.Contact.age >= 18 && profile.trait.Contact.country == "US" && has(profile.address.email)Max length: 2000

labelsobject

Optional

Labels to add, update, or remove using merge patch semantics.

To add or update a label: include the key with a string value
To remove a label: include the key with a null value
Labels not included in the request are left unchanged
Keys and values follow the same rules as on create: non-empty, URL-safe (A-Z, a-z, 0-9, -, ., _, ~), keys at most 128 characters, values at most 256, and no reserved twilio__ prefix on keys

Example: {"environment":"production","campaign":null}Max properties: 10

Show labels properties

Responses

202400401403404412422429500

Accepted - Operation accepted for asynchronous processing. Poll the CohortOperations endpoint to check status.

SchemaExample

Property nameTypeRequiredDescriptionChild properties

operationIdstring

read-only

Optional

Unique identifier for the operation following TTID format. Format: cmp_operation_{uuidv7-encoded}

Example: cmp_operation_01h9d8r0vte3hz8tykdj329t7rPattern: ^cmp_operation_[a-zA-Z0-9]{26}$Max length: 100

statusenum<string>

read-only

Optional

Current status of the operation.

PENDING: Operation is waiting to be processed
RUNNING: Operation is in progress
COMPLETED: Operation finished successfully
FAILED: Operation failed (check error field)
CANCELLED: Operation was cancelled by the user

Example: RUNNINGPossible values:

PENDINGRUNNINGCOMPLETEDFAILEDCANCELLED

statusUrlstring<uri-reference>

read-only

Optional

URL to poll for operation status

Example: /preview/CohortOperations/cmp_operation_01h9d8r0vte3hz8tykdj329t7rMax length: 500

createdAtstring<date-time>

read-only

Optional

Timestamp when the operation was created

Example: 2026-01-15T10:00:00Z

completedAtstring<date-time>

read-only

Optional

Timestamp when the operation completed (present for terminal states)

Example: 2026-01-15T10:03:45Z

payloadobject

read-only

Optional

Operation-specific metadata and progress information for a Cohort operation.

Show payload properties

resultUrlstring<uri-reference>

read-only

Optional

URL of the resulting resource. Present when status is COMPLETED and the operation produced or modified a resource.

Not present for deletion operations (DELETE, SNAPSHOT_DELETE) since the resource no longer exists after completion.

Example: /preview/CohortSnapshots/cmp_cohortsnapshot_01h9d8r0vte3hz8tykdj329t7rMax length: 500

resultobject

read-only

Optional

Operation-specific output data. Only present when status is COMPLETED. Fields present depend on operationType:

SNAPSHOT: cohortSnapshotId, cohortId (COHORT-sourced only), profileCount, partitionCount, updatedAt
SNAPSHOT_DELETE: cohortSnapshotId, cohortId (COHORT-sourced only)
UPDATE: cohortId, updatedAt
DELETE: cohortId

Show result properties

errorobject

read-only

Optional

Detailed error information following RFC 9457 Problem Details standard. Only present when status is FAILED.

Show error properties

Update a cohort definition

1UPDATE_COHORT_REQUEST_OBJ=$(cat << EOF
2{
3  "displayName": "Active US Adults"
4}
5EOF
6)
7curl -X PATCH "https://audiences.twilio.com/preview/Cohorts/cohortId" \
8--json "$UPDATE_COHORT_REQUEST_OBJ" \
9-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Response

1{
2  "operationId": "cmp_operation_01h9d8r0vte3hz8tykdj329t7r",
3  "status": "PENDING",
4  "statusUrl": "/preview/CohortOperations/cmp_operation_01h9d8r0vte3hz8tykdj329t7r",
5  "createdAt": "2026-01-15T10:00:00Z"
6}