Create a computed trait
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.
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.
displayNamestoreId: the profiles store the computation is performed ondefinition: which definition to run, with optional overridesisEnabled: 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 unknowndefinitionIdor store, parameters outside the definition'sparameterSchema, or an effective trait key whose type does not match the definition'svalueType.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.
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.
1Max length: 128application/jsonHuman-readable name of the computed trait
Marketing frequency capMin length: 1Max length: 128Optional
Optional description of the computed trait
Whether the profile has hit its weekly marketing send capMax length: 1024Optional
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 thetagsquery parameter of the list endpoints, so anything you can store here can also be filtered on. - Keys cannot use the reserved
twilio__prefix
{"environment":"production","campaign":"q1-2026"}Max properties: 10The profiles store the computation is performed on: its profiles are the ones computed over, and the computed value is written back onto them.
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.
Whether to start computing. Deliberately required rather than defaulted, so a caller never has to guess whether creating starts computing.
trueCreated - 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.
Optional
Unique identifier for a computed trait following TTID format.
Format: cmp_computedtrait_{uuidv7-encoded}
cmp_computedtrait_01h9d8r0vte3hz8tykdj329t9fPattern: ^cmp_computedtrait_[a-zA-Z0-9]{26}$Max length: 100Optional
Human-readable name of the computed trait
Marketing frequency capMin length: 1Max length: 128Optional
Optional description of the computed trait
Whether the profile has hit its weekly marketing send capMax length: 1024Optional
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 thetagsquery parameter of the list endpoints, so anything you can store here can also be filtered on. - Keys cannot use the reserved
twilio__prefix
{"environment":"production","campaign":"q1-2026"}Max properties: 10Optional
The profiles store the computation is performed on: its profiles are the ones computed over, and the computed value is written back onto them.
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.
Optional
Whether values are being computed and kept current
trueOptional
The trait the value is written to: definition.traitKey when
overridden, otherwise the definition's own traitKey.
SendIntelligence.weeklyCapMax length: 256Optional
The parameter values a run binds: each parameter's defaultValue from
the definition's parameterSchema, with any definition.parameters
overrides merged over them.
{"windowDays":7}Max properties: 32Optional
When the computed trait was created
2026-09-16T14:22:40ZOptional
When the computed trait's configuration last changed
2026-09-16T14:22:40ZOptional
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}.
cmp_operation_01h9d8r0vte3hz8tykdj329t7rPattern: ^cmp_operation_[a-zA-Z0-9]{26}$Max length: 1001CREATE_COMPUTED_TRAIT_REQUEST_OBJ=$(cat << EOF2{3"displayName": "Frequency cap",4"storeId": {},5"definition": {6"definitionId": "twilio.frequency_cap"7},8"isEnabled": true9}10EOF11)12curl -X POST "https://audiences.twilio.com/preview/ComputedTraits" \13--json "$CREATE_COMPUTED_TRAIT_REQUEST_OBJ" \14-u $TWILIO_API_KEY:$TWILIO_API_SECRET
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": 517},18"createdAt": "2026-09-16T14:22:40Z",19"updatedAt": "2026-09-16T14:22:40Z",20"operationId": "cmp_operation_01h9d8r0vte3hz8tykdj329t7r"21}