Skip to contentSkip to navigationSkip to topbar

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

POST/preview/ComputedTraits

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

The main call. Turns a definition on for one store.


Required fields

required-fields page anchor
  • displayName
  • storeId: the profiles store the computation is performed on
  • definition: which definition to run, with optional overrides
  • isEnabled: deliberately required rather than defaulted, so a caller never has to guess whether creating starts computing

The response is the new computed trait. When it is created enabled, it also carries operationId: poll GET /preview/ComputedTraitOperations/{computedTraitOperationId} with it until the operation reaches COMPLETED, which means the first values have landed on profiles. After that, read GET /preview/ComputedTraits/{computedTraitId}/Status for whether the values stay current. A computed trait created with isEnabled: false has nothing to compute yet, so it has no operationId.


  • 400: an unknown definitionId or store, parameters outside the definition's parameterSchema, or an effective trait key whose type does not match the definition's valueType.
  • 409: the effective trait key is already bound to another computed trait in this store, enabled or disabled. To reuse a key, update the disabled computed trait instead of creating a new one.

Headers

create-computed-trait-headers page anchor
Property nameTypeRequiredDescription
Idempotency-Keystring

Optional

Client-provided idempotency key for safe request retries.

When provided, the server ensures that duplicate requests with the same key produce the same result without executing the operation multiple times.

Requirements:

  • Must be a non-empty string (max 128 characters)
  • Keys are retained for at least 24 hours
  • Scope: Account + Region combination
  • If a different payload is sent with the same key, returns 422 Unprocessable Content

If a request is replayed with the same idempotency key, the response will include the header Idempotent-Replayed: true.

Min length: 1Max length: 128
Encoding type:application/json
SchemaExample
Property nameTypeRequiredDescriptionChild properties
displayNamestring
required

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
required

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
required

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
required

Whether to start computing. Deliberately required rather than defaulted, so a caller never has to guess whether creating starts computing.

Example: true

201400401403409422429500

Created - The computed trait exists now; its values land with the first run, tracked by operationId. Created with isEnabled: false, there is nothing to land and no operationId.

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
Create a computed traitLink to code sample: Create a computed trait
1
CREATE_COMPUTED_TRAIT_REQUEST_OBJ=$(cat << EOF
2
{
3
"displayName": "Frequency cap",
4
"storeId": {},
5
"definition": {
6
"definitionId": "twilio.frequency_cap"
7
},
8
"isEnabled": true
9
}
10
EOF
11
)
12
curl -X POST "https://audiences.twilio.com/preview/ComputedTraits" \
13
--json "$CREATE_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
"description": "Whether the profile has hit its weekly marketing send cap",
5
"tags": {
6
"team": "lifecycle"
7
},
8
"storeId": "mem_store_01h9d8r0vte3hz8tykdj329t7r",
9
"definition": {
10
"definitionId": "twilio.frequency_cap"
11
},
12
"isEnabled": true,
13
"traitKey": "SendIntelligence.weeklyCap",
14
"parameters": {
15
"windowDays": 7,
16
"maxSends": 5
17
},
18
"createdAt": "2026-09-16T14:22:40Z",
19
"updatedAt": "2026-09-16T14:22:40Z",
20
"operationId": "cmp_operation_01h9d8r0vte3hz8tykdj329t7r"
21
}