Segments

Create dynamic audience segments with rule-based membership and trigger recomputation.

Segments are dynamic groups of contacts defined by rules. Membership is computed automatically based on contact properties and event history. Use segments to target specific audiences in campaigns and sequences.

Create segment

POST /api/segments

Creates a new segment with the specified rules.

Request body

Field	Type	Required	Description
`name`	string	Yes	Human-readable name for the segment.
`rules`	object	Yes	Rule definition that determines membership. See Rule format.

Response

Returns the created segment.

{
  "id": "seg_01H9...",
  "name": "Active Pro Users",
  "rules": {
    "operator": "and",
    "conditions": [
      { "field": "properties.plan", "op": "eq", "value": "pro" },
      { "field": "events.login", "op": "occurred", "within": "30d" }
    ]
  },
  "memberCount": 0,
  "computedAt": null,
  "createdAt": "2025-09-15T10:00:00.000Z",
  "updatedAt": "2025-09-15T10:00:00.000Z"
}

Errors

Code	Description
`VALIDATION_ERROR`	Missing name or invalid rules.

Examples

curl -X POST https://api.kraiter.com/api/segments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Active Pro Users",
    "rules": {
      "operator": "and",
      "conditions": [
        { "field": "properties.plan", "op": "eq", "value": "pro" },
        { "field": "events.login", "op": "occurred", "within": "30d" }
      ]
    }
  }'

const segment = await kraiter.segments.create({
  name: "Active Pro Users",
  rules: {
    operator: "and",
    conditions: [
      { field: "properties.plan", op: "eq", value: "pro" },
      { field: "events.login", op: "occurred", within: "30d" },
    ],
  },
});

List segments

GET /api/segments

Returns a paginated list of segments.

Query parameters

Parameter	Type	Default	Description
`cursor`	string	—	Pagination cursor.
`limit`	number	20	Number of segments to return (max 100).

Examples

curl "https://api.kraiter.com/api/segments?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

const segments = await kraiter.segments.list({ limit: 10 });

Get segment

GET /api/segments/:id

Returns a single segment including its rules and membership count.

Path parameters

Parameter	Type	Description
`id`	string	The segment ID.

Errors

Code	Description
`NOT_FOUND`	No segment with this ID exists.

Examples

curl https://api.kraiter.com/api/segments/seg_01H9... \
  -H "Authorization: Bearer YOUR_API_KEY"

const segment = await kraiter.segments.get("seg_01H9...");

Update segment

PATCH /api/segments/:id

Updates a segment's name or rules. Changing the rules does not automatically recompute membership — call Compute segment to trigger recomputation.

Path parameters

Parameter	Type	Description
`id`	string	The segment ID.

Request body

Field	Type	Required	Description
`name`	string	No	New name for the segment.
`rules`	object	No	New rule definition.

Examples

curl -X PATCH https://api.kraiter.com/api/segments/seg_01H9... \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": {
      "operator": "and",
      "conditions": [
        { "field": "properties.plan", "op": "in", "value": ["pro", "enterprise"] },
        { "field": "events.login", "op": "occurred", "within": "7d" }
      ]
    }
  }'

const segment = await kraiter.segments.update("seg_01H9...", {
  rules: {
    operator: "and",
    conditions: [
      { field: "properties.plan", op: "in", value: ["pro", "enterprise"] },
      { field: "events.login", op: "occurred", within: "7d" },
    ],
  },
});

Delete segment

DELETE /api/segments/:id

Permanently deletes a segment. Campaigns referencing this segment are not affected but will no longer resolve its members.

Response

Returns 204 No Content on success.

Errors

Code	Description
`NOT_FOUND`	No segment with this ID exists.

Examples

curl -X DELETE https://api.kraiter.com/api/segments/seg_01H9... \
  -H "Authorization: Bearer YOUR_API_KEY"

await kraiter.segments.delete("seg_01H9...");

List segment members

GET /api/segments/:id/members

Returns the contacts that currently belong to this segment.

Path parameters

Parameter	Type	Description
`id`	string	The segment ID.

Query parameters

Parameter	Type	Default	Description
`cursor`	string	—	Pagination cursor.
`limit`	number	20	Number of members to return (max 100).

Response

{
  "data": [
    {
      "id": "cnt_01H8MZXK...",
      "email": "alice@example.com",
      "properties": { "plan": "pro" },
      "joinedAt": "2025-09-15T10:30:00.000Z"
    }
  ],
  "nextCursor": null
}

Examples

curl "https://api.kraiter.com/api/segments/seg_01H9.../members?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

const members = await kraiter.segments.listMembers("seg_01H9...", {
  limit: 50,
});

Compute segment

POST /api/segments/:id/compute

Triggers a recomputation of segment membership. This evaluates the segment rules against all contacts and updates the member list. Computation runs asynchronously — the response confirms the job has been queued.

Path parameters

Parameter	Type	Description
`id`	string	The segment ID.

Response

{
  "segmentId": "seg_01H9...",
  "status": "computing",
  "queuedAt": "2025-09-15T15:00:00.000Z"
}

Errors

Code	Description
`NOT_FOUND`	No segment with this ID exists.

Examples

curl -X POST https://api.kraiter.com/api/segments/seg_01H9.../compute \
  -H "Authorization: Bearer YOUR_API_KEY"

const result = await kraiter.segments.compute("seg_01H9...");

Rule format

Segment rules use a tree structure with logical operators and conditions.

Operators

Operator	Description
`and`	All conditions must be true.
`or`	At least one condition must be true.

Condition fields

Prefix	Description	Example
`properties.*`	Contact property value.	`properties.plan`
`events.*`	Event occurrence.	`events.purchase_completed`

Comparison operators

Operator	Description	Applies to
`eq`	Equals	Properties
`neq`	Not equals	Properties
`gt`	Greater than	Properties (numeric)
`gte`	Greater than or equal	Properties (numeric)
`lt`	Less than	Properties (numeric)
`lte`	Less than or equal	Properties (numeric)
`in`	Value is in list	Properties
`contains`	String contains	Properties (string)
`occurred`	Event has occurred	Events
`not_occurred`	Event has not occurred	Events

Time window

Event conditions support a within field to restrict the time window:

7d — within the last 7 days
30d — within the last 30 days
90d — within the last 90 days

Segments

On this page