/ai/segment/*chat | stream

API call to create and refine audience segments through AI-powered multi-turn conversation. The endpoint supports streaming (SSE) for real-time progress updates during segment generation.

The user must be authenticated and have read permissions to the siteGroup. The customer must have the AI feature enabled.

Endpoints

Path	Transport	Description
`/ai/segment/chat`	JSON (POST)	Non-streaming request/response
`/ai/segment/chat/stream`	SSE (POST)	Streaming with real-time progress events

The streaming endpoint returns Server-Sent Events (SSE) with progress updates as the AI processes the request, while the non-streaming endpoint returns a single JSON response. The streaming endpoint only supports start and message operations, while the non-streaming endpoint supports all five operations.

Request

Non-streaming endpoint (`/ai/segment/chat`)

Name	Type	Required	Description
`operation`	String	Yes	The chat operation to perform. One of: `start`, `message`, `list`, `history`, `end`
`siteGroupId`	String	Yes	The site group identifier to scope the conversation to
`conversationId`	String	Depends	The conversation identifier. Required for `message`, `history`, and `end` operations
`message`	String	Depends	The user's message text. Required for `start` and `message` operations. Must be non-empty
`userId`	String	No	Optional user identifier to associate with the conversation. Only used on `start`
`includeHistory`	boolean	No	Whether to include conversation history in the response. Defaults to `true`. Only for `start` and `message`
`maxHistoryMessages`	Integer	No	Limit the number of history messages returned. Returns most recent N messages. No limit by default

Streaming endpoint (/ai/segment/chat/stream)

Name	Type	Required	Description
`operation`	String	Yes	The chat operation to perform. Only `start` and `message` are supported
`siteGroupId`	String	Yes	The site group identifier to scope the conversation to
`conversationId`	String	Depends	The conversation identifier. Required for `message` operation
`message`	String	Yes	The user's message text. Must be non-empty
`userId`	String	No	Optional user identifier to associate with the conversation. Only used on `start`
`username`	String	No	Optional username override. Falls back to `X-cXense-Authentication` header if not provided

Operations

start - Start a New Conversation Begins a new AI segment chat conversation with an initial message. The AI will analyze the request, fetch relevant data from the site group, and generate a segment definition. Supported by both endpoints.

message - Send a Follow-up Message Sends a follow-up message in an existing conversation. The AI maintains context from previous messages and can refine or modify previously generated segments. Supported by both endpoints.

list - List Conversations Lists all conversations for the authenticated user, filtered by site group. Returns a summary of each conversation including the first message and creation time. Non-streaming endpoint only.

history - Get Conversation History Retrieves the full message history for an existing conversation. Non-streaming endpoint only.

end - End a Conversation Ends and cleans up a conversation. The conversation data will expire shortly after. Non-streaming endpoint only.

Response

Non-streaming response (`/ai/segment/chat`)

For `start` and `message` operations

Name	Type	Description
`conversationId`	String	Unique identifier for the conversation
`responseText`	Object	Thr generated segment definition as a JSON object
`conversationHistory`	Array of object	List of chat messages (empty if `includeHistory` is `false`)
`success`	boolean	Whether the operation succeeded
`error`	String	Error message if the operation failed

For `list` operation

Name	Type	Description
`conversations`	Array of object	Array of conversation summary objects

A conversation summary object has the following fields:

Name	Type	Description
`conversationId`	String	Unique identifier for the conversation
`siteGroupId`	String	The site group identifier
`createdAt`	Number	Unix timestamp in milliseconds when the conversation started
`firstMessage`	String	Preview of the first message (truncated to 100 characters)

For `history` operation

Name	Type	Description
`messages`	Array of object	Array of chat messages

For `end` operation

Name	Type	Description
`success`	boolean	Whether the conversation was ended

Chat message object

Messages in conversationHistory and messages arrays have the following fields:

Name	Type	Description
`role`	String	`"user"` or `"assistant"`
`content`	String	The message text
`timestamp`	Number	Unix timestamp in milliseconds
`segmentJson`	Object/null	Parsed segment definition JSON, if the message contains one

Streaming response (`/ai/segment/chat/stream`)

The streaming endpoint returns Server-Sent Events. Each event is a JSON object with an eventType field:

eventType	Description	Key fields
`thinking`	The AI is analyzing the request	`message`
`tool_call`	The AI is fetching data from the platform	`toolName`, `toolArgs`, `message`
`tool_result`	A data fetch completed	`toolName`, `message`
`complete`	The segment has been generated	`conversationId`, `responseText`, `conversationHistory`, `success`
`error`	An error occurred	`message`, `success`

Segment response object

The responseText field contains the generated segment definition:

Name	Type	Description
`name`	String	Name of the generated segment
`description`	String	Description of the generated segment
`inferred`	String	The inferred segment type: `traffic` or `lookalike`
`filters`	Array of object	Segment filter definitions. See Traffic filters for syntax
`chat_message`	String	A conversational summary of what was created or changed

Examples

Start a conversation (non-streaming)

Bash

$ python cx.py /ai/segment/chat '{"operation": "start", "siteGroupId": "1135172335968227720", "message": "Create a segment for users from Chicago on Safari who read Robert Herguth articles"}'
{
 "conversationId": "e70245d5-0c6e-4dd9-a455-3f02b8de9c19",
 "responseText": {
 "name": "Chicago Safari Users Reading Robert Herguth",
 "description": "Users from Chicago using Safari browser who read articles by Robert Herguth",
 "inferred": "traffic",
 "filters": [
 {
 "type": "time",
 "start": "-30d",
 "filter": {
 "type": "user",
 "having": {
 "min": 1,
 "filter": {
 "type": "and",
 "filters": [
 {
 "type": "event",
 "group": "city",
 "items": ["chicago"]
 },
 {
 "type": "event",
 "group": "browser",
 "items": ["Safari"]
 },
 {
 "type": "keyword",
 "group": "author",
 "items": ["robert herguth"]
 }
 ]
 }
 }
 }
 }
 ],
 "chat_message": "Created your segment targeting Chicago users on Safari who read Robert Herguth articles. Would you like to adjust anything?"
 },
 "conversationHistory": [
 {
 "role": "user",
 "content": "Create a segment for users from Chicago on Safari who read Robert Herguth articles",
 "timestamp": 1709654400000,
 "segmentJson": null
 },
 {
 "role": "assistant",
 "content": "Created your segment targeting Chicago users on Safari who read Robert Herguth articles. Would you like to adjust anything?",
 "timestamp": 1709654415000,
 "segmentJson": { "..." }
 }
 ],
 "success": true,
 "error": null
}

Send a follow-up message

Bash

$ python cx.py /ai/segment/chat '{"operation": "message", "siteGroupId": "1135172335968227720", "conversationId": "e70245d5-0c6e-4dd9-a455-3f02b8de9c19", "message": "Exclude users from Norway"}'
{
 "conversationId": "e70245d5-0c6e-4dd9-a455-3f02b8de9c19",
 "responseText": {
 "name": "Chicago Safari Users Reading Robert Herguth (Excluding Norway)",
 "description": "Users from Chicago using Safari browser who read articles by Robert Herguth, excluding users from Norway",
 "inferred": "traffic",
 "filters": ["..."],
 "chat_message": "Updated your segment to exclude Norwegian users. Any other adjustments needed?"
 },
 "conversationHistory": ["..."],
 "success": true,
 "error": null
}

List conversations

Bash

$ python cx.py /ai/segment/chat '{"operation": "list", "siteGroupId": "1135172335968227720"}'
{
 "conversations": [
 {
 "conversationId": "e70245d5-0c6e-4dd9-a455-3f02b8de9c19",
 "siteGroupId": "1135172335968227720",
 "createdAt": 1709654400000,
 "firstMessage": "Create a segment for users from Chicago on Safari who read Robert Herguth articles"
 }
 ]
}

Get conversation history

Bash

$ python cx.py /ai/segment/chat '{"operation": "history", "siteGroupId": "1135172335968227720", "conversationId": "e70245d5-0c6e-4dd9-a455-3f02b8de9c19"}'
{
 "messages": [
 {
 "role": "user",
 "content": "Create a segment for users from Chicago on Safari who read Robert Herguth articles",
 "timestamp": 1709654400000,
 "segmentJson": null
 },
 {
 "role": "assistant",
 "content": "Created your segment targeting Chicago users on Safari who read Robert Herguth articles. Would you like to adjust anything?",
 "timestamp": 1709654415000,
 "segmentJson": { "..." }
 }
 ]
}

End a conversation

Bash

$ python cx.py /ai/segment/chat '{"operation": "end", "siteGroupId": "1135172335968227720", "conversationId": "e70245d5-0c6e-4dd9-a455-3f02b8de9c19"}'
{
 "success": true
}

Streaming example (SSE events)

Bash

$ python cx.py /ai/segment/chat/stream '{"operation": "start", "siteGroupId": "1135172335968227720", "message": "Create a segment for sports fans"}'
data: {
 "conversationId": "abc-123",
 "eventType": "thinking",
 "message": "Analyzing request..."
}

data: {
 "eventType": "tool_call",
 "toolName": "list_keyword_groups",
 "message": "Discovering keyword groups..."
}

data: {
 "eventType": "tool_result",
 "toolName": "list_keyword_groups",
 "message": "Discovering keyword groups done"
}

data: {
 "eventType": "tool_call",
 "toolName": "get_keyword_items",
 "message": "Fetching keyword data..."
}

data: {
 "eventType": "tool_result",
 "toolName": "get_keyword_items",
 "message": "Fetching keyword data done"
}

data: {
 "conversationId": "abc-123",
 "eventType": "complete",
 "responseText": {...},
 "conversationHistory": [...],
 "success": true
}

Error Responses

Non-streaming endpoint (`/ai/segment/chat`)

Condition	HTTP Status	Error message
Missing `siteGroupId`	400	`siteGroupId parameter is required`
Missing `operation`	400	`operation parameter is required`
Missing `conversationId`	400	`conversationId parameter is required`
Empty message	400	`Message must be provided and cannot be empty`
Unknown operation	400	`Unknown chat operation: <operation>`
Conversation expired	200	`{"error": "Conversation not found or expired"}`
Service unavailable	200	`{"error": "AI segment chat service is not available"}`

Streaming endpoint (`/ai/segment/chat/stream`)

Validation errors are returned as SSE events with eventType: "error" rather than HTTP error codes:

Condition	Error message
Missing `siteGroupId` or `operation`	HTTP 400: `siteGroupId and operation are required`
Invalid JSON request	HTTP 400: `Invalid JSON request`
Missing `conversationId`	SSE: `{"eventType":"error","message":"conversationId is required"}`
Empty message	SSE: `{"eventType":"error","message":"message is required"}`
Unsupported operation	SSE: `{"eventType":"error","message":"Streaming only supports 'start' and 'message' operations"}`
Internal error	SSE: `{"eventType":"error","message":"An internal error occurred. Please try again.","success":false}`

Last updated: March 17, 2026

Endpoints

Request

Non-streaming endpoint (/ai/segment/chat)

Streaming endpoint (/ai/segment/chat/stream)

Operations

Response

Non-streaming response (/ai/segment/chat)

For start and message operations

For list operation

For history operation

For end operation

Chat message object

Streaming response (/ai/segment/chat/stream)

Segment response object

Examples

Start a conversation (non-streaming)

Send a follow-up message

List conversations

Get conversation history

End a conversation

Streaming example (SSE events)

Error Responses

Non-streaming endpoint (/ai/segment/chat)

Streaming endpoint (/ai/segment/chat/stream)

Non-streaming endpoint (`/ai/segment/chat`)

Non-streaming response (`/ai/segment/chat`)

For `start` and `message` operations

For `list` operation

For `history` operation

For `end` operation

Streaming response (`/ai/segment/chat/stream`)

Non-streaming endpoint (`/ai/segment/chat`)

Streaming endpoint (`/ai/segment/chat/stream`)