Segments API

CRUD for Segments: saved predicates that decide who a journey, letter, or export includes.

The product word is Segment. /api/audiences still exists as deprecated plumbing. New callers use /api/segments. When you push a Segment to Meta or Google, that export is an Audience in the ad platform's vocabulary.

List segments

GET/api/segments

List segments in the workspace or org

Parameter	Type	Description
`scope`	`string`	workspace (default) or org
`workspaceKey`	`string`	Workspace to list when scope is workspace
`includeArchived`	`string`	Pass 1 to include archived segments

[
  {
    "id": "seg-pro-tier-active",
    "workspaceKey": "your-workspace-key",
    "name": "Pro tier, active in last 7d",
    "scope": "workspace",
    "predicate": {},
    "createdAt": "2026-04-15T12:00:00.000Z",
    "updatedAt": "2026-04-30T14:22:00.000Z"
  }
]

Create a segment

POST/api/segments

Create a new segment

Parameter	Type	Description
`name`required	`string`	Display name
`scope`required	`string`	workspace or org
`predicate`required	`SegmentPredicate`	The predicate tree
`workspaceKey`	`string`	Required for workspace scope

Update / delete

PATCH/api/segments/[id]

Update name, description, or predicate

DELETE/api/segments/[id]

Delete the segment. Journeys that referenced it need a new segment before they will match anyone.

Preview and reach

POST/api/segments/preview

Preview who matches a predicate without saving

GET/api/segments/[id]/reach

How many people currently match

Predicate language

A predicate is one of:

Leaves

{ "kind": "event_fired",
  "eventName": "checkout_started",
  "window": { "type": "last_n_days", "days": 7 },
  "atLeast": 2
}

{ "kind": "event_not_fired",
  "eventName": "purchase",
  "window": { "type": "last_n_days", "days": 30 }
}

{ "kind": "attribute",
  "fieldPath": "tier",
  "operator": "equals",
  "value": "pro"
}

{ "kind": "in_segment", "segmentId": "power-users" }

Composites

{ "kind": "and", "clauses": [ "<predicate>", "<predicate>" ] }
{ "kind": "or",  "clauses": [ "<predicate>", "<predicate>" ] }
{ "kind": "not", "clause":   "<predicate>" }

Window types

{ "type": "ever" }
{ "type": "last_n_days", "days": 7 }

Attribute operators

equals, not_equals, exists, not_exists, greater_than, less_than, in.

exists / not_exists ignore value. in matches comma-separated values.