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.
`description`	string	No	Optional description of the segment.
`enabled`	boolean	No	Whether the segment is active. Defaults to `true`.

Response

Returns the created segment.

{
  "segmentId": "seg_01H9...",
  "name": "Active Pro Users",
  "description": null,
  "rules": {
    "operator": "and",
    "conditions": [
      { "type": "property", "field": "plan", "operator": "equals", "value": "pro" },
      { "type": "derived", "field": "totalOpens", "operator": "greaterThan", "value": 0 }
    ]
  },
  "enabled": true,
  "memberCount": 0,
  "dependsOn": [],
  "dependedBy": [],
  "version": "01H9...",
  "lastComputedAt": 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.
`CIRCULAR_DEPENDENCY`	A `segment` condition would create a cycle between segments.

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": [
        { "type": "property", "field": "plan", "operator": "equals", "value": "pro" },
        { "type": "derived", "field": "totalOpens", "operator": "greaterThan", "value": 0 }
      ]
    }
  }'

const segment = await kraiter.segments.create({
  name: "Active Pro Users",
  rules: {
    operator: "and",
    conditions: [
      { type: "property", field: "plan", operator: "equals", value: "pro" },
      { type: "derived", field: "totalOpens", operator: "greaterThan", value: 0 },
    ],
  },
});

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
`SEGMENT_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.
`description`	string	No	New description.
`enabled`	boolean	No	Enable or disable the segment.

At least one field must be provided.

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": [
        { "type": "property", "field": "plan", "operator": "includes", "value": ["pro", "enterprise"] },
        { "type": "derived", "field": "inactiveDays", "operator": "lessThan", "value": 7 }
      ]
    }
  }'

const segment = await kraiter.segments.update("seg_01H9...", {
  rules: {
    operator: "and",
    conditions: [
      { type: "property", field: "plan", operator: "includes", value: ["pro", "enterprise"] },
      { type: "derived", field: "inactiveDays", operator: "lessThan", value: 7 },
    ],
  },
});

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
`SEGMENT_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 membership records for contacts that currently belong to this segment. Each record identifies the contact by contactId — hydrate full contact details with the Contacts API if needed.

Path parameters

Parameter	Type	Description
`id`	string	The segment ID.

Query parameters

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

Response

{
  "items": [
    {
      "contactId": "cnt_01H8MZXK...",
      "isMember": true,
      "computedAt": "2025-09-15T10:30:00.000Z",
      "version": "01H9..."
    }
  ],
  "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

Recomputes segment membership by evaluating the rules against every contact and updating the member list. This runs synchronously and returns counts once complete. It can be expensive for large tenants and is rate-limited to roughly once per minute per segment.

Path parameters

Parameter	Type	Description
`id`	string	The segment ID.

Response

{
  "segmentId": "seg_01H9...",
  "processed": 1240,
  "changed": 37
}

Field	Type	Description
`processed`	number	Number of contacts evaluated.
`changed`	number	Number of contacts whose membership changed.

Errors

Code	Description
`SEGMENT_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 are a recursive tree. A rule node has a logical operator and a conditions array; each entry in conditions is either a leaf condition or a nested rule node, so you can build arbitrarily deep boolean expressions.

{
  "operator": "and",
  "conditions": [
    { "type": "property", "field": "plan", "operator": "equals", "value": "pro" },
    {
      "operator": "or",
      "conditions": [
        { "type": "derived", "field": "totalClicks", "operator": "greaterThan", "value": 0 },
        { "type": "segment", "segmentId": "seg_vip", "operator": "memberOf" }
      ]
    }
  ]
}

Logical operators

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

Condition types

Every leaf condition has a type that selects which contact data it reads:

Type	Shape	Reads
`property`	`{ type, field, operator, value }`	`contact.properties.<field>` (your custom properties).
`derived`	`{ type, field, operator, value }`	`contact.derived.<field>` (system-computed engagement fields such as `totalOpens`, `totalClicks`, `inactiveDays`, `lastEventAt`).
`segment`	`{ type, segmentId, operator }`	Membership in another segment.

Comparison operators

Used by property and derived conditions:

Operator	Description
`equals` / `notEquals`	Equality comparison.
`greaterThan` / `lessThan`	Numeric comparison.
`greaterOrEqual` / `lessOrEqual`	Numeric comparison (inclusive).
`contains` / `notContains`	Substring check on a string value.
`startsWith` / `endsWith`	String prefix / suffix check.
`includes` / `notIncludes`	Array membership (does the field/value contain the given item).
`includesAll` / `includesAny`	Array contains all / any of the given items.
`exists` / `notExists`	Whether the field is present.

Segment operators

Used by segment conditions:

Operator	Description
`memberOf`	Contact is a member of the referenced segment.
`notMemberOf`	Contact is not a member of the referenced segment.

Segments

On this page