Skip to contentSkip to navigationSkip to topbar

Update a computed trait


(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(link takes you to an external page). 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

update-computed-trait-request page anchor

Headers

update-computed-trait-headers page anchor
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
Property nameTypeRequiredDescription
computedTraitIdstring
required

The computedTraitId identifier

Encoding type:application/json
SchemaExample
Property nameTypeRequiredDescriptionChild properties
displayNamestring

Optional

Human-readable name of the computed trait

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
Example: {"environment":"production","campaign":null}Max properties: 10

isEnabledboolean

Optional

Turn computation on or off

Example: true

storeIdobject

Optional

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.


200400401403404412422429500

OK - The updated computed trait. Carries operationId when the change has to be computed (enabling, or changing parameters); otherwise none.

SchemaExample
Property nameTypeRequiredDescriptionChild properties
idstring
read-only

Optional

Unique identifier for a computed trait following TTID format. Format: cmp_computedtrait_{uuidv7-encoded}

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

displayNamestring

Optional

Human-readable name of the computed trait

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.
  • Keys cannot use the reserved twilio__ prefix
Example: {"environment":"production","campaign":"q1-2026"}Max properties: 10

storeIdobject

Optional

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.


isEnabledboolean

Optional

Whether values are being computed and kept current

Example: true

traitKeystring
read-only

Optional

The trait the value is written to: definition.traitKey when overridden, otherwise the definition's own traitKey.

Example: SendIntelligence.weeklyCapMax length: 256

parametersobject
read-only

Optional

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}.

Example: cmp_operation_01h9d8r0vte3hz8tykdj329t7rPattern: ^cmp_operation_[a-zA-Z0-9]{26}$Max length: 100
Update a computed traitLink to code sample: Update a computed trait
1
UPDATE_COMPUTED_TRAIT_REQUEST_OBJ=$(cat << EOF
2
{
3
"isEnabled": true,
4
"definition": {
5
"parameters": {
6
"windowDays": 14
7
}
8
}
9
}
10
EOF
11
)
12
curl -X PATCH "https://audiences.twilio.com/preview/ComputedTraits/computedTraitId" \
13
--json "$UPDATE_COMPUTED_TRAIT_REQUEST_OBJ" \
14
-u $TWILIO_API_KEY:$TWILIO_API_SECRET

Response

Note about this response
1
{
2
"id": "cmp_computedtrait_01h9d8r0vte3hz8tykdj329t9f",
3
"displayName": "Marketing frequency cap",
4
"storeId": "mem_store_01h9d8r0vte3hz8tykdj329t7r",
5
"definition": {
6
"parameters": {
7
"windowDays": 14
8
}
9
},
10
"isEnabled": true,
11
"traitKey": "SendIntelligence.weeklyCap",
12
"parameters": {
13
"windowDays": 14,
14
"maxSends": 5
15
},
16
"createdAt": "2026-09-16T14:22:40Z",
17
"updatedAt": "2026-09-22T16:40:00Z",
18
"operationId": "cmp_operation_01h9d8r0vte3hz8tykdj32cd5e"
19
}