/ai/segment/create | Documentation

API call to generate audience segmentation rules from natural language descriptions using AI.

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

Request

The request object has the following fields:

Name	Type	Required	Description
`prompt`	String	Yes	Natural language description of the audience segment to create
`siteGroupId`	Array of String	Yes	Site group identifier where the segment will be created

Either id for a single segment or ids for batch requests must be provided.

Response

The response object for a successful query has the following fields:

Name	Type	Description
`name`	String	Generated name for the segment
`description`	String	AI-generated description of the segment
`inferred`	String	Segment type inferred from the prompt: traffic, contextual, or lookalike
`filters`	Array of Objects	Array of filter objects defining the segment rules

Segment Types (Inferred Fields)

The AI system automatically determines the segment type based on your natural language prompt:

Type	Description	Example Prompts
`traffic`	User/behavioral segments based on historical activity	"Users who visited sports pages", "Mobile users from Germany"
`contextual`	Content-based segments targeting current page properties	"Articles about technology", "Brand-safe content"
`lookalike`	Similarity-based segments expanding from existing audiences	"Users similar to our subscribers", "Expand audience X"

Filter Objects

Filter objects define the actual segmentation criteria and follow the standard CX platform filter structure used throughout the segment APIs.

AI Segment Generation The segment rules are generated using AI-powered analysis of your natural language prompt. The AI service interprets your intent and converts it into appropriate filters and criteria. If the AI segment creator service is unavailable, an error response will be returned.

Error Responses

When the AI service cannot create a valid segment, the response will contain:

Name	Type	Description
`name`	String	Empty string
`description`	String	Error message describing why the segment cannot be created
`inferred`	String	Empty string
`filters`	Array of object	Empty array
`reason`	String	Failure reason (same as description)

When the service is completely unavailable, the response will contain:

Name	Type	Description
`error`	String	Error message describing the failure

Common error scenarios:

Invalid or unclear prompts: When the AI cannot understand the segment requirements
"Service failed": The AI service processed the request but encountered an error
"AI segment creator service is not available": The AI service is unavailable or unreachable

Examples

Bash

$ python cx.py /ai/segment/create '{"prompt": "Segment for users from Germany", "siteGroupId": "1135172335968227720"}'
{
 "name": "Users from Germany",
 "description": "Users located in Germany",
 "inferred": "traffic",
 "filters": [
 {
 "type": "time",
 "start": "-30d",
 "filter": {
 "type": "event",
 "group": "country",
 "item": "de"
 }
 }
 ]
}
$ python cx.py /ai/segment/create '{"prompt": "Articles about artificial intelligence published in the last week", "siteGroupId": "abc123"}'
{
 "name": "Recent AI Articles",
 "description": "Content about artificial intelligence published within the past week",
 "inferred": "contextual",
 "filters": [
 {
 "type": "time",
 "start": "-7d",
 "stop": "-0d",
 "filter": {
 "type": "and",
 "filters": [
 {
 "type": "keyword",
 "group": "publishtime",
 "start": "-7d",
 "stop": "-0d"
 },
 {
 "type": "keyword",
 "group": "term",
 "items": ["artificial intelligence", "AI", "machine learning"]
 }
 ]
 }
 }
 ]
}
$ python cx.py /ai/segment/create '{"prompt": "bla bla bla", "siteGroupId": "1135172335968227720"}' # Invalid prompt
{
 "name": "",
 "description": "Invalid or unclear segment request - please provide a specific audience targeting criteria",
 "inferred": "",
 "filters": [],
 "reason": "Invalid or unclear segment request - please provide a specific audience targeting criteria"
}
$ python cx.py /ai/segment/create '{"prompt": "Active users", "siteGroupId": "abc123"}' # When service unavailable
{
 "error": "AI segment creator service is not available"
}

Usage Notes

Natural Language Flexibility: The AI service can interpret various natural language patterns and convert them into appropriate segment filters
Complex Criteria: You can describe complex multi-dimensional criteria in natural language (e.g., combining behavioral, demographic, and temporal aspects)
Validation: The generated filters follow standard CX platform conventions and can be used with other segment APIs
Prompt Quality: More specific and detailed prompts typically result in more accurate segment generation

Last updated: March 17, 2026