API call to generate natural language descriptions of one or more audience segmentation rules.
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 |
|---|---|---|---|
|
|
String |
No |
Return the description for the audience segmentation rule with the given id. |
|
|
Array of String |
No |
Return descriptions for the audience segmentation rules with the given identifiers. |
Either id for a single segment or ids for batch requests must be provided.
Response
The response object has the following fields:
|
Name |
Type |
Description |
|---|---|---|
|
|
Object |
Array of segment description objects |
A segment description object has the following fields:
|
Name |
Type |
Description |
|---|---|---|
|
|
String |
The identifier for the audience segment |
|
|
String |
Natural language description of what the segment captures |
|
|
boolean |
True if the description was generated successfully |
Description Generation The segment descriptions are generated using AI-powered analysis of the segment rules and filters. If the segment descriptor service is unavailable, the success field will be false and a fallback message will be provided.
Examples
$ python cx.py /ai/segment/describe '{"id": "a9yrr02o79yo"}'
{
"descriptions": [
{
"segmentId": "a9yrr02o79yo",
"description": "This segment captures activity during the past 7 days. It includes visits from users who have read at least 7 articles and then selects the top half of those readers who mostly focus on dataroom content.",
"success": true
}
]
}
$ python cx.py /ai/segment/describe '{"ids": ["a9yrr02o79yo", "aaksxojme8q5"]}'
{
"descriptions": [
{
"segmentId": "a9yrr02o79yo",
"description": "This segment shows data from the past 7 days for visitors who read at least 7 articles. It then focuses on the top 50% of these users—the ones who most often read content related to the dataroom category.",
"success": true
},
{
"segmentId": "aaksxojme8q5",
"description": "This segment focuses on content published within the past 31 days. It aims to help you check that your pages are properly tagged with their publication dates—if you're not seeing enough URLs, it may suggest an issue with how the site is set up to supply that information.",
"success": true
}
]
}
$ python cx.py /ai/segment/describe '{"id": "a9yrr02o79yo"}' # When service unavailable
{
"descriptions": [
{
"segmentId": "a9yrr02o79yo",
"description": "Segment description service is not available",
"success": false
}
]
}