Segments

Segments are predicate definitions over traits and event history, recomputed synchronously on each write and again when a time window in a definition lapses. Transitions emit system.segment_entered and system.segment_exited system events that automations trigger on, except those found by a bulk recompute or an import, which start nobody. See the Segments guide for predicate semantics. All mutations require organization admin permissions.

POST /v1/segments

Create a segment

Auth: Session token.

Request body

{
  "data": {
    "name": "string",
    "appId": "string",
    "description": "string",
    "definition": {
      "match": "all",
      "predicates": [
        {
          "kind": "trait",
          "name": "string",
          "op": "eq",
          "value": {}
        }
      ]
    }
  }
}

Field	Type	Required	Constraints
data	object	yes
data.name	string	yes	length 1–100
data.appId	string	yes	length 0–200
data.description	string | null	no
data.definition	object	yes
data.definition.match	“all” | “any”	no	default "all"
data.definition.predicates	array of variants	yes	items 1–∞
data.definition.predicates[]	one of	yes
data.definition.predicates[]〈trait〉	object	yes
data.definition.predicates[]〈trait〉.kind	“trait”	yes
data.definition.predicates[]〈trait〉.name	string	yes	length 1–200
data.definition.predicates[]〈trait〉.op	“eq” | “neq” | “gt” | “gte” | “lt” | “lte” | “exists” | “notExists” | “contains” | “before” | “after”	yes
data.definition.predicates[]〈trait〉.value	any	no
data.definition.predicates[]〈event〉	object	yes
data.definition.predicates[]〈event〉.kind	“event”	yes
data.definition.predicates[]〈event〉.name	string | string[]	yes
data.definition.predicates[]〈event〉.op	“performed” | “notPerformed”	yes
data.definition.predicates[]〈event〉.atLeast	integer	no	default 1; 1 ≤ x ≤ ∞
data.definition.predicates[]〈event〉.withinDays	integer	no	1 ≤ x ≤ ∞

Response 201

{
  "data": {
    "id": "string",
    "orgId": "string",
    "appId": "string",
    "name": "string",
    "description": "string",
    "tags": [
      "string"
    ],
    "definition": {
      "match": "all",
      "predicates": [
        {
          "kind": "trait",
          "name": "string",
          "op": "eq",
          "value": {}
        }
      ]
    },
    "source": "push",
    "automationKey": "string",
    "createdAt": "2026-01-15T09:30:00.000Z",
    "updatedAt": "2026-01-15T09:30:00.000Z",
    "memberCount": 42
  },
  "meta": {
    "requestId": "string",
    "nextCursor": "string",
    "hasMore": true,
    "warnings": [
      {
        "code": "string",
        "message": "string",
        "suggestion": "string"
      }
    ]
  }
}

Field	Type	Required	Constraints
data	object	yes
data.id	string	yes
data.orgId	string	yes
data.appId	string	yes
data.name	string	yes
data.description	string | null	yes
data.tags	string[]	yes
data.definition	object	yes
data.definition.match	“all” | “any”	yes	default "all"
data.definition.predicates	array of variants	yes	items 1–∞
data.definition.predicates[]	one of	yes
data.definition.predicates[]〈trait〉	object	yes
data.definition.predicates[]〈trait〉.kind	“trait”	yes
data.definition.predicates[]〈trait〉.name	string	yes	length 1–200
data.definition.predicates[]〈trait〉.op	“eq” | “neq” | “gt” | “gte” | “lt” | “lte” | “exists” | “notExists” | “contains” | “before” | “after”	yes
data.definition.predicates[]〈trait〉.value	any	no
data.definition.predicates[]〈event〉	object	yes
data.definition.predicates[]〈event〉.kind	“event”	yes
data.definition.predicates[]〈event〉.name	string | string[]	yes
data.definition.predicates[]〈event〉.op	“performed” | “notPerformed”	yes
data.definition.predicates[]〈event〉.atLeast	integer	yes	default 1; 1 ≤ x ≤ ∞
data.definition.predicates[]〈event〉.withinDays	integer	no	1 ≤ x ≤ ∞
data.source	“push” | “api”	yes
data.automationKey	string | null	yes
data.createdAt	string (date-time)	yes
data.updatedAt	string (date-time)	yes
data.memberCount	integer	yes	0 ≤ x ≤ ∞
meta	object	no
meta.requestId	string	no
meta.nextCursor	string | null	no
meta.hasMore	boolean	no
meta.warnings	object[]	no
meta.warnings[]	object	no
meta.warnings[].code	string	yes
meta.warnings[].message	string	yes
meta.warnings[].suggestion	string	no

Errors follow the shared envelope and code table.

POST /v1/segments/preview

Preview a draft definition

Auth: Session token.

Request body

{
  "data": {
    "appId": "string",
    "definition": {
      "match": "all",
      "predicates": [
        {
          "kind": "trait",
          "name": "string",
          "op": "eq",
          "value": {}
        }
      ]
    }
  }
}

Field	Type	Required	Constraints
data	object	yes
data.appId	string	yes	length 0–200
data.definition	object	yes
data.definition.match	“all” | “any”	no	default "all"
data.definition.predicates	array of variants	yes	items 1–∞
data.definition.predicates[]	one of	yes
data.definition.predicates[]〈trait〉	object	yes
data.definition.predicates[]〈trait〉.kind	“trait”	yes
data.definition.predicates[]〈trait〉.name	string	yes	length 1–200
data.definition.predicates[]〈trait〉.op	“eq” | “neq” | “gt” | “gte” | “lt” | “lte” | “exists” | “notExists” | “contains” | “before” | “after”	yes
data.definition.predicates[]〈trait〉.value	any	no
data.definition.predicates[]〈event〉	object	yes
data.definition.predicates[]〈event〉.kind	“event”	yes
data.definition.predicates[]〈event〉.name	string | string[]	yes
data.definition.predicates[]〈event〉.op	“performed” | “notPerformed”	yes
data.definition.predicates[]〈event〉.atLeast	integer	no	default 1; 1 ≤ x ≤ ∞
data.definition.predicates[]〈event〉.withinDays	integer	no	1 ≤ x ≤ ∞

Response 200

{
  "data": {
    "memberCount": 42,
    "members": [
      "string"
    ],
    "scanned": 42,
    "truncated": true
  },
  "meta": {
    "requestId": "string",
    "nextCursor": "string",
    "hasMore": true,
    "warnings": [
      {
        "code": "string",
        "message": "string",
        "suggestion": "string"
      }
    ]
  }
}

Field	Type	Required	Constraints
data	object	yes
data.memberCount	integer	yes	0 ≤ x ≤ ∞
data.members	string[]	yes
data.scanned	integer	yes	0 ≤ x ≤ ∞
data.truncated	boolean	yes
meta	object	no
meta.requestId	string	no
meta.nextCursor	string | null	no
meta.hasMore	boolean	no
meta.warnings	object[]	no
meta.warnings[]	object	no
meta.warnings[].code	string	yes
meta.warnings[].message	string	yes
meta.warnings[].suggestion	string	no

Errors follow the shared envelope and code table.

GET /v1/segments

List segments

Auth: Session token.

Query parameters

{
  "cursor": "string",
  "limit": 50,
  "q": "string",
  "appId": "string"
}

Field	Type	Required	Constraints
cursor	string	no
limit	integer	no	default 50; 1 ≤ x ≤ 100
q	string	no	length 0–200
appId	string	no	length 0–200

Response 200

{
  "data": [
    {
      "id": "string",
      "orgId": "string",
      "appId": "string",
      "name": "string",
      "description": "string",
      "tags": [
        "string"
      ],
      "definition": {
        "match": "all",
        "predicates": [
          {
            "kind": "trait",
            "name": "string",
            "op": "eq",
            "value": {}
          }
        ]
      },
      "source": "push",
      "automationKey": "string",
      "createdAt": "2026-01-15T09:30:00.000Z",
      "updatedAt": "2026-01-15T09:30:00.000Z"
    }
  ],
  "meta": {
    "requestId": "string",
    "nextCursor": "string",
    "hasMore": true,
    "warnings": [
      {
        "code": "string",
        "message": "string",
        "suggestion": "string"
      }
    ]
  }
}

Field	Type	Required	Constraints
data	object[]	yes
data[]	object	yes
data[].id	string	yes
data[].orgId	string	yes
data[].appId	string	yes
data[].name	string	yes
data[].description	string | null	yes
data[].tags	string[]	yes
data[].definition	object	yes
data[].definition.match	“all” | “any”	yes	default "all"
data[].definition.predicates	array of variants	yes	items 1–∞
data[].definition.predicates[]	one of	yes
data[].definition.predicates[]〈trait〉	object	yes
data[].definition.predicates[]〈trait〉.kind	“trait”	yes
data[].definition.predicates[]〈trait〉.name	string	yes	length 1–200
data[].definition.predicates[]〈trait〉.op	“eq” | “neq” | “gt” | “gte” | “lt” | “lte” | “exists” | “notExists” | “contains” | “before” | “after”	yes
data[].definition.predicates[]〈trait〉.value	any	no
data[].definition.predicates[]〈event〉	object	yes
data[].definition.predicates[]〈event〉.kind	“event”	yes
data[].definition.predicates[]〈event〉.name	string | string[]	yes
data[].definition.predicates[]〈event〉.op	“performed” | “notPerformed”	yes
data[].definition.predicates[]〈event〉.atLeast	integer	yes	default 1; 1 ≤ x ≤ ∞
data[].definition.predicates[]〈event〉.withinDays	integer	no	1 ≤ x ≤ ∞
data[].source	“push” | “api”	yes
data[].automationKey	string | null	yes
data[].createdAt	string (date-time)	yes
data[].updatedAt	string (date-time)	yes
meta	object	no
meta.requestId	string	no
meta.nextCursor	string | null	no
meta.hasMore	boolean	no
meta.warnings	object[]	no
meta.warnings[]	object	no
meta.warnings[].code	string	yes
meta.warnings[].message	string	yes
meta.warnings[].suggestion	string	no

Errors follow the shared envelope and code table.

GET /v1/segments/{id}

Fetch one segment with its member count

Auth: Session token.

Response 200

{
  "data": {
    "id": "string",
    "orgId": "string",
    "appId": "string",
    "name": "string",
    "description": "string",
    "tags": [
      "string"
    ],
    "definition": {
      "match": "all",
      "predicates": [
        {
          "kind": "trait",
          "name": "string",
          "op": "eq",
          "value": {}
        }
      ]
    },
    "source": "push",
    "automationKey": "string",
    "createdAt": "2026-01-15T09:30:00.000Z",
    "updatedAt": "2026-01-15T09:30:00.000Z",
    "memberCount": 42
  },
  "meta": {
    "requestId": "string",
    "nextCursor": "string",
    "hasMore": true,
    "warnings": [
      {
        "code": "string",
        "message": "string",
        "suggestion": "string"
      }
    ]
  }
}

Field	Type	Required	Constraints
data	object	yes
data.id	string	yes
data.orgId	string	yes
data.appId	string	yes
data.name	string	yes
data.description	string | null	yes
data.tags	string[]	yes
data.definition	object	yes
data.definition.match	“all” | “any”	yes	default "all"
data.definition.predicates	array of variants	yes	items 1–∞
data.definition.predicates[]	one of	yes
data.definition.predicates[]〈trait〉	object	yes
data.definition.predicates[]〈trait〉.kind	“trait”	yes
data.definition.predicates[]〈trait〉.name	string	yes	length 1–200
data.definition.predicates[]〈trait〉.op	“eq” | “neq” | “gt” | “gte” | “lt” | “lte” | “exists” | “notExists” | “contains” | “before” | “after”	yes
data.definition.predicates[]〈trait〉.value	any	no
data.definition.predicates[]〈event〉	object	yes
data.definition.predicates[]〈event〉.kind	“event”	yes
data.definition.predicates[]〈event〉.name	string | string[]	yes
data.definition.predicates[]〈event〉.op	“performed” | “notPerformed”	yes
data.definition.predicates[]〈event〉.atLeast	integer	yes	default 1; 1 ≤ x ≤ ∞
data.definition.predicates[]〈event〉.withinDays	integer	no	1 ≤ x ≤ ∞
data.source	“push” | “api”	yes
data.automationKey	string | null	yes
data.createdAt	string (date-time)	yes
data.updatedAt	string (date-time)	yes
data.memberCount	integer	yes	0 ≤ x ≤ ∞
meta	object	no
meta.requestId	string	no
meta.nextCursor	string | null	no
meta.hasMore	boolean	no
meta.warnings	object[]	no
meta.warnings[]	object	no
meta.warnings[].code	string	yes
meta.warnings[].message	string	yes
meta.warnings[].suggestion	string	no

Errors follow the shared envelope and code table.

PATCH /v1/segments/{id}

Update a segment

Updating a segment’s definition recomputes its membership over existing profile history. A segment from your project’s segments/ directory can be updated here too; the next push that would overwrite the change asks first. The segment an automation’s trigger defines changes only with that automation.

Auth: Session token.

Request body

{
  "data": {
    "name": "string",
    "description": "string",
    "definition": {
      "match": "all",
      "predicates": [
        {
          "kind": "trait",
          "name": "string",
          "op": "eq",
          "value": {}
        }
      ]
    }
  }
}

Field	Type	Required	Constraints
data	object	yes
data.name	string	no	length 1–100
data.description	string | null	no
data.definition	object	no
data.definition.match	“all” | “any”	no	default "all"
data.definition.predicates	array of variants	yes	items 1–∞
data.definition.predicates[]	one of	yes
data.definition.predicates[]〈trait〉	object	yes
data.definition.predicates[]〈trait〉.kind	“trait”	yes
data.definition.predicates[]〈trait〉.name	string	yes	length 1–200
data.definition.predicates[]〈trait〉.op	“eq” | “neq” | “gt” | “gte” | “lt” | “lte” | “exists” | “notExists” | “contains” | “before” | “after”	yes
data.definition.predicates[]〈trait〉.value	any	no
data.definition.predicates[]〈event〉	object	yes
data.definition.predicates[]〈event〉.kind	“event”	yes
data.definition.predicates[]〈event〉.name	string | string[]	yes
data.definition.predicates[]〈event〉.op	“performed” | “notPerformed”	yes
data.definition.predicates[]〈event〉.atLeast	integer	no	default 1; 1 ≤ x ≤ ∞
data.definition.predicates[]〈event〉.withinDays	integer	no	1 ≤ x ≤ ∞

Response 200

{
  "data": {
    "id": "string",
    "orgId": "string",
    "appId": "string",
    "name": "string",
    "description": "string",
    "tags": [
      "string"
    ],
    "definition": {
      "match": "all",
      "predicates": [
        {
          "kind": "trait",
          "name": "string",
          "op": "eq",
          "value": {}
        }
      ]
    },
    "source": "push",
    "automationKey": "string",
    "createdAt": "2026-01-15T09:30:00.000Z",
    "updatedAt": "2026-01-15T09:30:00.000Z",
    "memberCount": 42
  },
  "meta": {
    "requestId": "string",
    "nextCursor": "string",
    "hasMore": true,
    "warnings": [
      {
        "code": "string",
        "message": "string",
        "suggestion": "string"
      }
    ]
  }
}

Field	Type	Required	Constraints
data	object	yes
data.id	string	yes
data.orgId	string	yes
data.appId	string	yes
data.name	string	yes
data.description	string | null	yes
data.tags	string[]	yes
data.definition	object	yes
data.definition.match	“all” | “any”	yes	default "all"
data.definition.predicates	array of variants	yes	items 1–∞
data.definition.predicates[]	one of	yes
data.definition.predicates[]〈trait〉	object	yes
data.definition.predicates[]〈trait〉.kind	“trait”	yes
data.definition.predicates[]〈trait〉.name	string	yes	length 1–200
data.definition.predicates[]〈trait〉.op	“eq” | “neq” | “gt” | “gte” | “lt” | “lte” | “exists” | “notExists” | “contains” | “before” | “after”	yes
data.definition.predicates[]〈trait〉.value	any	no
data.definition.predicates[]〈event〉	object	yes
data.definition.predicates[]〈event〉.kind	“event”	yes
data.definition.predicates[]〈event〉.name	string | string[]	yes
data.definition.predicates[]〈event〉.op	“performed” | “notPerformed”	yes
data.definition.predicates[]〈event〉.atLeast	integer	yes	default 1; 1 ≤ x ≤ ∞
data.definition.predicates[]〈event〉.withinDays	integer	no	1 ≤ x ≤ ∞
data.source	“push” | “api”	yes
data.automationKey	string | null	yes
data.createdAt	string (date-time)	yes
data.updatedAt	string (date-time)	yes
data.memberCount	integer	yes	0 ≤ x ≤ ∞
meta	object	no
meta.requestId	string	no
meta.nextCursor	string | null	no
meta.hasMore	boolean	no
meta.warnings	object[]	no
meta.warnings[]	object	no
meta.warnings[].code	string	yes
meta.warnings[].message	string	yes
meta.warnings[].suggestion	string	no

Errors follow the shared envelope and code table.

DELETE /v1/segments/{id}

Delete a segment

Deleting a segment permanently removes all of its members. A segment from your project’s segments/ directory comes back on the next push that carries its file. The segment an automation’s trigger defines goes only with that automation.

Auth: Session token.

Response 200

{
  "data": {
    "deleted": true
  },
  "meta": {
    "requestId": "string",
    "nextCursor": "string",
    "hasMore": true,
    "warnings": [
      {
        "code": "string",
        "message": "string",
        "suggestion": "string"
      }
    ]
  }
}

Field	Type	Required	Constraints
data	object	yes
data.deleted	true	yes
meta	object	no
meta.requestId	string	no
meta.nextCursor	string | null	no
meta.hasMore	boolean	no
meta.warnings	object[]	no
meta.warnings[]	object	no
meta.warnings[].code	string	yes
meta.warnings[].message	string	yes
meta.warnings[].suggestion	string	no

Errors follow the shared envelope and code table.

GET /v1/segments/{id}/members

List a segment’s members

Auth: Session token.

Query parameters

{
  "cursor": "string",
  "limit": 50
}

Field	Type	Required	Constraints
cursor	string	no
limit	integer	no	default 50; 1 ≤ x ≤ 100

Response 200

{
  "data": [
    {
      "segmentId": "string",
      "orgId": "string",
      "profileId": "string",
      "enteredAt": "2026-01-15T09:30:00.000Z"
    }
  ],
  "meta": {
    "requestId": "string",
    "nextCursor": "string",
    "hasMore": true,
    "warnings": [
      {
        "code": "string",
        "message": "string",
        "suggestion": "string"
      }
    ]
  }
}

Field	Type	Required	Constraints
data	object[]	yes
data[]	object	yes
data[].segmentId	string	yes
data[].orgId	string	yes
data[].profileId	string	yes
data[].enteredAt	string (date-time)	yes
meta	object	no
meta.requestId	string	no
meta.nextCursor	string | null	no
meta.hasMore	boolean	no
meta.warnings	object[]	no
meta.warnings[]	object	no
meta.warnings[].code	string	yes
meta.warnings[].message	string	yes
meta.warnings[].suggestion	string	no

Errors follow the shared envelope and code table.