Documentation

Segment API

Programmatically manage audiences using the Segment API.

Overview

The Segment API allows you to programmatically create, update, delete, and query audiences. While most audience management can be done through the Lytics UI, the API is useful for automating audience workflows, integrating with external systems, or building custom tooling.

Core Operations

List Segments

GET /v2/segment

Returns all segments for the account.

Get a Segment

GET /v2/segment/{id}

Returns details of a specific segment, including its SegmentQL definition, membership size, and metadata.

Create a Segment

POST /v2/segment

Creates a new segment.

Request Body

{
  "name": "Frequent Visitors",
  "slug_name": "frequent_visitors",
  "is_public": true,
  "table": "user",
  "segment_ql": "FILTER AND (visits > 5) FROM user"
}
🚧

Compare one key of a map field, not the whole map

A condition on a map field has to name a key, as in conversion_ts.purchase > "now-7d". A condition that compares the whole map to a value, such as conversion_ts > "now-7d" (or ==, !=, LIKE, CONTAINS, or BETWEEN), never matched anyone, so creating or updating a segment with one returns 400 with a reason that names the field. Existing segments with such a condition are marked invalid and stop updating, along with any segment that includes them; update the condition to compare one key to clear it. EXISTS, IN, and INTERSECTS on a whole map check its keys and still work.

📘

Compare one field to another

A condition can compare two date fields, or two number fields, with <, <=, >, or >=, as in last_purchase_ts > last_email_click_ts. Dates compare by whole UTC day, not by the exact time. Comparing two fields with = or !=, or two fields of different types, returns 400. A profile missing either field doesn't match. For birthdays and other anniversaries, see recurring.

Update a Segment

PUT /v2/segment/{id}

Updates an existing segment's definition, name, or other properties.

Delete a Segment

DELETE /v2/segment/{id}

Deletes a segment. This does not delete the underlying user profiles.

Advanced Operations

Reevaluate a Segment

POST /v2/segment/{id}/reevaluate

Triggers a full reevaluation of segment membership. Normally, segment membership is updated in real-time as profile data changes. Use reevaluation when:

  • You've made significant schema changes that affect segment criteria
  • You need to force a full recalculation of membership
  • You suspect membership drift due to processing delays
📘

Reevaluation runs asynchronously. For large segments, it may not complete immediately.

Segment Ancestry

GET /v2/segment/{id}/ancestors

Returns the lineage of a segment -- the parent segments that this segment depends on or is derived from. This is useful for understanding segment composition when segments reference other segments in their definitions.

Segment Jobs

GET /v2/segment/{id}/jobs

Returns the workflow jobs associated with a segment, including active exports and imports.

Segment Groups

Segment groups allow you to organize audiences into logical folders.

List Groups

GET /v2/segment/group

Create a Group

POST /v2/segment/group

Request Body

{
  "name": "Campaign Audiences",
  "description": "Audiences used for Q1 campaigns"
}

Update a Group

PUT /v2/segment/group/{id}

Delete a Group

DELETE /v2/segment/group/{id}

Deleting a group does not delete the segments within it.

Related

Updated 10 days ago

Did this page help you?