Segments

List segments

GET/v1/segments

Scope: segments:read. MCP tool: list_segments.

View saved customer segments, newest first, with their member counts and last update time. Filter by active, archived or all. Returns up to 200 segments per page by default, with a maximum of 500; pass next_cursor as cursor for the next page.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Query Parameters

status?string|null

limit?integer

cursor?|

next_cursor from the previous page.

Response Body

`application/json`

curl -X GET "https://example.com/v1/segments"

{  "data": [    {      "id": "string",      "name": "string",      "description": "string",      "status": "active",      "current_version_id": "string",      "created_by": "string",      "created_at": "string",      "updated_at": "string",      "audience": {        "evaluation_status": "not_evaluated",        "member_count": 0,        "generation": 0,        "evaluated_at": "string",        "last_run_at": "string",        "current_version_evaluated": true      }    }  ],  "next_cursor": "string"}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

Create a segment

POST/v1/segments

Requires sign-in (OAuth). Scope: segments:write. MCP tool: create_segment.

Create a customer segment using your chosen rules. Members update within the next 15-minute refresh. Use estimate_segment to check its size before saving. Invalid rules return the field that needs correcting.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

description?|

definition*

Response Body

`application/json`

curl -X POST "https://example.com/v1/segments" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "definition": {      "property1": null,      "property2": null    }  }'

{  "id": "string",  "name": "string",  "description": "string",  "status": "active",  "current_version_id": "string",  "created_by": "string",  "created_at": "string",  "updated_at": "string",  "audience": {    "evaluation_status": "not_evaluated",    "member_count": 0,    "generation": 0,    "evaluated_at": "string",    "last_run_at": "string",    "current_version_evaluated": true  },  "version": 0,  "schema_version": 0,  "definition": {    "property1": null,    "property2": null  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

Estimate segment size

POST/v1/segments/estimate

Scope: segments:read. MCP tool: estimate_segment.

Check how many customers match a segment. Supply a draft definition or the ID of a saved segment. Results can take a few seconds.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

definition?

segment_id?string

Response Body

`application/json`

curl -X POST "https://example.com/v1/segments/estimate" \  -H "Content-Type: application/json" \  -d '{}'

{  "count": 0,  "segment_id": "string",  "version": 0,  "estimated_at": "string"}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

Segment details

GET/v1/segments/{id}

Scope: segments:read. MCP tool: get_segment.

View a segment’s rules, version and latest member count.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

`application/json`

curl -X GET "https://example.com/v1/segments/string"

{  "id": "string",  "name": "string",  "description": "string",  "status": "active",  "current_version_id": "string",  "created_by": "string",  "created_at": "string",  "updated_at": "string",  "audience": {    "evaluation_status": "not_evaluated",    "member_count": 0,    "generation": 0,    "evaluated_at": "string",    "last_run_at": "string",    "current_version_evaluated": true  },  "version": 0,  "schema_version": 0,  "definition": {    "property1": null,    "property2": null  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

Change a segment's rule

PATCH/v1/segments/{id}

Requires sign-in (OAuth). Scope: segments:write. MCP tool: update_segment.

Update a segment’s rules. Previous versions are kept. Archived segments cannot be edited.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

definition*

Response Body

`application/json`

curl -X PATCH "https://example.com/v1/segments/string" \  -H "Content-Type: application/json" \  -d '{    "definition": {      "property1": null,      "property2": null    }  }'

{  "id": "string",  "name": "string",  "description": "string",  "status": "active",  "current_version_id": "string",  "created_by": "string",  "created_at": "string",  "updated_at": "string",  "audience": {    "evaluation_status": "not_evaluated",    "member_count": 0,    "generation": 0,    "evaluated_at": "string",    "last_run_at": "string",    "current_version_evaluated": true  },  "version": 0,  "schema_version": 0,  "definition": {    "property1": null,    "property2": null  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

Archive a segment

POST/v1/segments/{id}/archive

Requires sign-in (OAuth). Scope: segments:write. MCP tool: archive_segment.

Archive a segment to stop updates and remove it from the active list. Its history is kept and its name can be reused. Remove references from other active segments before archiving.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

`application/json`

curl -X POST "https://example.com/v1/segments/string/archive"

{  "id": "string",  "name": "string",  "description": "string",  "status": "active",  "current_version_id": "string",  "created_by": "string",  "created_at": "string",  "updated_at": "string",  "audience": {    "evaluation_status": "not_evaluated",    "member_count": 0,    "generation": 0,    "evaluated_at": "string",    "last_run_at": "string",    "current_version_evaluated": true  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

Segment audience

GET/v1/segments/{id}/audience

Scope: segments:read. MCP tool: get_segment_audience.

View a segment’s latest member count, update time and status. Segments you create refresh every 15 minutes; the built-in lifecycle segments refresh hourly (Visitors, Customers, Repeat Customers, Active Subscribers) or every 4 hours (High Value, At Risk, Churned). A new segment shows not_evaluated until its first update, within 15 minutes.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

`application/json`

curl -X GET "https://example.com/v1/segments/string/audience"

{  "evaluation_status": "not_evaluated",  "member_count": 0,  "generation": 0,  "evaluated_at": "string",  "last_run_at": "string",  "current_version_evaluated": true,  "segment_id": "string",  "message": "string"}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

Segment members

GET/v1/segments/{id}/members

Scope: segments:read. MCP tool: list_segment_members.

View the customers in a segment, with their email and phone number. Results reflect the latest segment update and are ordered by customer ID. Use cursor for the next page. The default page size is 100; the maximum is 5,000.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Query Parameters

limit?integer

cursor?string|null

Response Body

`application/json`

curl -X GET "https://example.com/v1/segments/string/members"

{  "data": [    {      "customer_id": "string",      "email": "string",      "phone": "string",      "lr_contact_id": "string",      "joined_at": "string"    }  ],  "next_cursor": "string",  "generation": 0}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

Segment join and leave history

GET/v1/segments/{id}/history

Scope: segments:read. MCP tool: list_segment_history.

See who joined or left a segment, newest updates first. Filter by customer_id to include a customer’s linked profiles. Use cursor for the next page. The default page size is 100; the maximum is 1,000. History covers 180 days.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Query Parameters

customer_id?string|null

limit?integer

cursor?string|null

Response Body

`application/json`

curl -X GET "https://example.com/v1/segments/string/history"

{  "data": [    {      "customer_id": "string",      "email": "string",      "phone": "string",      "current_customer_id": "string",      "action": "entered",      "reason": "string",      "generation": 0,      "changed_at": "string"    }  ],  "next_cursor": "string"}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`