Segments API

A segment is a named group of contacts used for cohort analysis and agent targeting. Define segments in the dashboard; the API lets you list them and fetch their members.

All endpoints require segments:read.

List Segments

GET /v1/segments

Query Parameters

Parameter	Type	Default	Description
page	number	1	Page number.
limit	number	50	Results per page (1–100).

Response — 200 OK

{
  "status": "success",
  "segments": [
    {
      "_id": "seg_abc",
      "name": "Pricing visitors — last 7d",
      "description": "Anyone who hit /pricing in the last 7 days",
      "contact_count": 42,
      "filter": { /* segment definition */ },
      "created_at": "2026-04-12T09:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total_pages": 1, "total_items": 8 }
}

---

Get a Segment

GET /v1/segments/:segment_id

Returns the segment definition without its members. Use the next endpoint to page through members.

Response — 200 OK

{
  "status": "success",
  "segment": {
    "_id": "seg_abc",
    "name": "Pricing visitors — last 7d",
    "filter": { /* segment definition */ },
    "contact_count": 42
  }
}

---

Get Segment Contacts

GET /v1/segments/:segment_id/contacts

Returns the contacts in a segment, paginated.

Query Parameters

Parameter	Type	Default	Description
page	number	1	Page number.
limit	number	20	Results per page (1–100).

Response — 200 OK

{
  "status": "success",
  "segment_name": "Pricing visitors — last 7d",
  "contacts": [
    {
      "_id": "ct_abc",
      "properties": {
        "email": "[email protected]",
        "firstname": "Ada",
        "lastname": "Lovelace",
        "company": "Analytical Engines",
        "jobtitle": "Founder",
        "lifecyclestage": "lead"
      },
      "company_id": "co_xyz",
      "segment_ids": ["seg_abc"],
      "created_at": "2026-04-29T08:14:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total_pages": 3, "total_items": 42 }
}

Use this endpoint to answer questions like “show me all contacts in the pricing-visitors segment” without rebuilding the segment’s filter from raw events.

For programmatic cross-segment queries (e.g. “by industry, count contacts in the pricing-visitors segment”), use the Aggregate endpoint with entity: "contacts" and a filters.segment_id.