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/ComputedTraits/{computedTraitId}
Base url: https://audiences.twilio.com (base url)
Toggle a computed trait off or on, retune its parameters, or rename it.
Supports If-Match for optimistic concurrency (412 on mismatch).
Mutable:isEnabled, displayName, description, tags (RFC 7396
merge-patch), and definition.parameters (replaces the overrides as a
whole).
Immutable:storeId, definition.definitionId, and
definition.traitKey. They are accepted only when unchanged; a different
value returns 422 (24007). Moving where a value lands is a new computed
trait, not an edit.
Always returns 200 with the computed trait. When a run has to land the
change (an ENABLE for isEnabled false to true, an UPDATE for a parameter
change on an enabled trait) the response carries operationId, and Status
moves to UPDATING. Renaming, tags, description and disabling carry no
operationId. Disabling cancels any operation still in flight.
Request
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.
Example: Marketing frequency capMin length: 1Max length: 128
descriptionstring
Optional
Optional description of the computed trait
Example: Whether the profile has hit its weekly marketing send capMax length: 1024
tagsobject
Optional
Tags to add, update, or remove using merge patch semantics.
To add or update a tag: include the key with a string value
To remove a tag: include the key with a null value
Tags 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
The profiles store the computation is performed on: its profiles are the
ones computed over, and the computed value is written back onto them.
definitionobject
Optional
Changes to the definition reference. Only parameters is mutable, and it
replaces the overrides as a whole. definitionId and traitKey are
accepted only when unchanged; a different value returns 422.
Fully qualified trait key, TraitGroup.traitName. Its format is checked
against the store's trait schema rather than a local pattern, so it follows
whatever names the store allows.
Example: Marketing frequency capMin length: 1Max length: 128
descriptionstring
Optional
Optional description of the computed trait
Example: Whether the profile has hit its weekly marketing send capMax length: 1024
tagsobject
Optional
Tags for organizing and categorizing resources as key-value pairs.
Maximum of 10 key-value pairs
Maximum size of a tag key is 128 characters
Maximum size of a tag value is 256 characters
Keys and values must be non-empty and URL-safe: only unreserved characters
(A-Z, a-z, 0-9, -, ., _, ~) are allowed. Tags are echoed back
in the tags query parameter of the list endpoints, so anything you can
store here can also be filtered on.
The profiles store the computation is performed on: its profiles are the
ones computed over, and the computed value is written back onto them.
definitionobject
Optional
What the computed trait runs: one of the shapes listed, told apart by which
field is present. Phase one has a single shape, the reference
(definitionId).
The oneOf is declared now so later shapes are additive. Phase two (inline
definitions, out of scope) adds a shape carrying expression instead of
definitionId. Each shape requires its own field and sets
additionalProperties: false, so a body matches exactly one; a body with
both fields, or neither, matches none and returns 400. When reading a
computed trait, check which field is present rather than assuming
definitionId.
The parameter values a run binds: each parameter's defaultValue from
the definition's parameterSchema, with any definition.parameters
overrides merged over them.
Example: {"windowDays":7}Max properties: 32
createdAtstring<date-time>
read-only
Optional
When the computed trait was created
Example: 2026-09-16T14:22:40Z
updatedAtstring<date-time>
read-only
Optional
When the computed trait's configuration last changed
Example: 2026-09-16T14:22:40Z
operationIdstring
read-only
Optional
The ComputedTraitOperation tracking this change, on the response to a create,
an enable, or a parameter change only. Never returned by a GET of the
trait, so it is never stale. Poll
GET /preview/ComputedTraitOperations/{operationId}.
Bad Request - The request was invalid or cannot be processed.
Request-schema failures list every failing field in errors[]. Criteria and
variable expressions are checked after that, one at a time: the first
invalid expression is reported in detail, with no errors[]. Query-parameter
checks the schema cannot express, such as storeType without storeId, return
24001 with no errors[].
The HTTP status code generated by the origin server for this occurrence
of the problem. MUST match the HTTP status code returned in the response.
Example: 400
codeinteger
Optional
Twilio-specific error code (extension member per RFC-9457 Section 3.2).
Numeric code uniquely identifying the error type within Twilio's error
taxonomy. Registered at https://www.twilio.com/docs/api/errors.
Example: 24000
detailstring
Optional
A human-readable explanation specific to this occurrence of the problem.
May vary between occurrences of the same problem type.
Example: The 'name' parameter is required but was not provided.Min length: 16Max length: 1024
instancestring<uri-reference>
Optional
A URI reference identifying the specific occurrence of the problem;
typically the request path.
Array of field-level errors for HTTP 400/422 responses. Each entry
identifies a single failure with a JSON Pointer to its location.
When more than 50 field errors would be emitted, the array is truncated
to 50 entries and the 50th entry's detail describes the truncation.
Example: [{"detail":"displayName is required and must be a non-empty value","pointer":"#/displayName"},{"detail":"criteria is required and must be a non-empty value","pointer":"#/criteria"}]Max items: 50
The HTTP status code generated by the origin server for this occurrence
of the problem. MUST match the HTTP status code returned in the response.
Example: 400
codeinteger
Optional
Twilio-specific error code (extension member per RFC-9457 Section 3.2).
Numeric code uniquely identifying the error type within Twilio's error
taxonomy. Registered at https://www.twilio.com/docs/api/errors.
Example: 24000
detailstring
Optional
A human-readable explanation specific to this occurrence of the problem.
May vary between occurrences of the same problem type.
Example: The 'name' parameter is required but was not provided.Min length: 16Max length: 1024
instancestring<uri-reference>
Optional
A URI reference identifying the specific occurrence of the problem;
typically the request path.
Array of field-level errors for HTTP 400/422 responses. Each entry
identifies a single failure with a JSON Pointer to its location.
When more than 50 field errors would be emitted, the array is truncated
to 50 entries and the 50th entry's detail describes the truncation.
Example: [{"detail":"displayName is required and must be a non-empty value","pointer":"#/displayName"},{"detail":"criteria is required and must be a non-empty value","pointer":"#/criteria"}]Max items: 50
The HTTP status code generated by the origin server for this occurrence
of the problem. MUST match the HTTP status code returned in the response.
Example: 400
codeinteger
Optional
Twilio-specific error code (extension member per RFC-9457 Section 3.2).
Numeric code uniquely identifying the error type within Twilio's error
taxonomy. Registered at https://www.twilio.com/docs/api/errors.
Example: 24000
detailstring
Optional
A human-readable explanation specific to this occurrence of the problem.
May vary between occurrences of the same problem type.
Example: The 'name' parameter is required but was not provided.Min length: 16Max length: 1024
instancestring<uri-reference>
Optional
A URI reference identifying the specific occurrence of the problem;
typically the request path.
Array of field-level errors for HTTP 400/422 responses. Each entry
identifies a single failure with a JSON Pointer to its location.
When more than 50 field errors would be emitted, the array is truncated
to 50 entries and the 50th entry's detail describes the truncation.
Example: [{"detail":"displayName is required and must be a non-empty value","pointer":"#/displayName"},{"detail":"criteria is required and must be a non-empty value","pointer":"#/criteria"}]Max items: 50
The HTTP status code generated by the origin server for this occurrence
of the problem. MUST match the HTTP status code returned in the response.
Example: 400
codeinteger
Optional
Twilio-specific error code (extension member per RFC-9457 Section 3.2).
Numeric code uniquely identifying the error type within Twilio's error
taxonomy. Registered at https://www.twilio.com/docs/api/errors.
Example: 24000
detailstring
Optional
A human-readable explanation specific to this occurrence of the problem.
May vary between occurrences of the same problem type.
Example: The 'name' parameter is required but was not provided.Min length: 16Max length: 1024
instancestring<uri-reference>
Optional
A URI reference identifying the specific occurrence of the problem;
typically the request path.
Array of field-level errors for HTTP 400/422 responses. Each entry
identifies a single failure with a JSON Pointer to its location.
When more than 50 field errors would be emitted, the array is truncated
to 50 entries and the 50th entry's detail describes the truncation.
Example: [{"detail":"displayName is required and must be a non-empty value","pointer":"#/displayName"},{"detail":"criteria is required and must be a non-empty value","pointer":"#/criteria"}]Max items: 50
The HTTP status code generated by the origin server for this occurrence
of the problem. MUST match the HTTP status code returned in the response.
Example: 400
codeinteger
Optional
Twilio-specific error code (extension member per RFC-9457 Section 3.2).
Numeric code uniquely identifying the error type within Twilio's error
taxonomy. Registered at https://www.twilio.com/docs/api/errors.
Example: 24000
detailstring
Optional
A human-readable explanation specific to this occurrence of the problem.
May vary between occurrences of the same problem type.
Example: The 'name' parameter is required but was not provided.Min length: 16Max length: 1024
instancestring<uri-reference>
Optional
A URI reference identifying the specific occurrence of the problem;
typically the request path.
Array of field-level errors for HTTP 400/422 responses. Each entry
identifies a single failure with a JSON Pointer to its location.
When more than 50 field errors would be emitted, the array is truncated
to 50 entries and the 50th entry's detail describes the truncation.
Example: [{"detail":"displayName is required and must be a non-empty value","pointer":"#/displayName"},{"detail":"criteria is required and must be a non-empty value","pointer":"#/criteria"}]Max items: 50
The HTTP status code generated by the origin server for this occurrence
of the problem. MUST match the HTTP status code returned in the response.
Example: 400
codeinteger
Optional
Twilio-specific error code (extension member per RFC-9457 Section 3.2).
Numeric code uniquely identifying the error type within Twilio's error
taxonomy. Registered at https://www.twilio.com/docs/api/errors.
Example: 24000
detailstring
Optional
A human-readable explanation specific to this occurrence of the problem.
May vary between occurrences of the same problem type.
Example: The 'name' parameter is required but was not provided.Min length: 16Max length: 1024
instancestring<uri-reference>
Optional
A URI reference identifying the specific occurrence of the problem;
typically the request path.
Array of field-level errors for HTTP 400/422 responses. Each entry
identifies a single failure with a JSON Pointer to its location.
When more than 50 field errors would be emitted, the array is truncated
to 50 entries and the 50th entry's detail describes the truncation.
Example: [{"detail":"displayName is required and must be a non-empty value","pointer":"#/displayName"},{"detail":"criteria is required and must be a non-empty value","pointer":"#/criteria"}]Max items: 50
The HTTP status code generated by the origin server for this occurrence
of the problem. MUST match the HTTP status code returned in the response.
Example: 400
codeinteger
Optional
Twilio-specific error code (extension member per RFC-9457 Section 3.2).
Numeric code uniquely identifying the error type within Twilio's error
taxonomy. Registered at https://www.twilio.com/docs/api/errors.
Example: 24000
detailstring
Optional
A human-readable explanation specific to this occurrence of the problem.
May vary between occurrences of the same problem type.
Example: The 'name' parameter is required but was not provided.Min length: 16Max length: 1024
instancestring<uri-reference>
Optional
A URI reference identifying the specific occurrence of the problem;
typically the request path.
Array of field-level errors for HTTP 400/422 responses. Each entry
identifies a single failure with a JSON Pointer to its location.
When more than 50 field errors would be emitted, the array is truncated
to 50 entries and the 50th entry's detail describes the truncation.
Example: [{"detail":"displayName is required and must be a non-empty value","pointer":"#/displayName"},{"detail":"criteria is required and must be a non-empty value","pointer":"#/criteria"}]Max items: 50
The HTTP status code generated by the origin server for this occurrence
of the problem. MUST match the HTTP status code returned in the response.
Example: 400
codeinteger
Optional
Twilio-specific error code (extension member per RFC-9457 Section 3.2).
Numeric code uniquely identifying the error type within Twilio's error
taxonomy. Registered at https://www.twilio.com/docs/api/errors.
Example: 24000
detailstring
Optional
A human-readable explanation specific to this occurrence of the problem.
May vary between occurrences of the same problem type.
Example: The 'name' parameter is required but was not provided.Min length: 16Max length: 1024
instancestring<uri-reference>
Optional
A URI reference identifying the specific occurrence of the problem;
typically the request path.
Array of field-level errors for HTTP 400/422 responses. Each entry
identifies a single failure with a JSON Pointer to its location.
When more than 50 field errors would be emitted, the array is truncated
to 50 entries and the 50th entry's detail describes the truncation.
Example: [{"detail":"displayName is required and must be a non-empty value","pointer":"#/displayName"},{"detail":"criteria is required and must be a non-empty value","pointer":"#/criteria"}]Max items: 50