/segment/read | Documentation

API call to retrieve one or more audience segmentation rule.

The user must be authenticated and have read permissions to the siteGroup.

Request

The request object has the following fields:

Name	Type	Required	Description
`siteGroupId`	String	No	Return all audience segmentation rules for the given site group identifier
`siteGroupIds`	Array	No	Return all audience segmentation rules for the given site groups identifiers
`id`	String	No	Return the audience segmentation rule for the given id.
`annotations`	Array of object	No	Return the audience segmentation rules that matches the given annotations.
`category`	String	No	Return the audience segmentation rules that matches the given category.
`group`	String	No	Return the audience segmentation rules that matches the given group.
`showShortId`	boolean	No	Return the audience segmentation rules with shortened segment identifier if it exists.
`type`	String	No	Return all the audience segmentation rules for the given type. It cannot be combined with 'id'.

The read request will return all segments for the user if no parameters are given.

Annotations

List of key value pairs. Max size of list is 1000.

Name	Type	Description
`key`	String	Must be unique and less than 256 characters. Must start with a letter and can only contain ascii characters a-z, A-Z, 0-9 or _ (underscore). Case sensitive. This means that two strings like test and Test are not considered as duplicates.
`value`	String	Less than 256 characters

Response

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

Name	Type	Description
`segments`	Array of object	Array of audience segment objects

An audience segment object has the following fields:

Name	Type	Description
`id`	String	The identifier for the audience segment
`shortId`	String	The shortened identifier for the audience segment.
`siteGroupId`	String	The site group identifier to which this audience segment belongs
`name`	String	The name of this audience segment
`description`	String	A description for this audience segment
`type`	String	The type of the segment, either `traffic`, `external`, `dmp` or `combined`
`filters`	Array of object	Array of filters that defines the segment. The filter syntax is documented here .
`annotations`	Array of object	Key/value pairs that can be used to look up the segment
`active`	boolean	True if segment is enabled for active usage. Explained below.
`internal`	boolean	True to make the segment internal to protect from nonadmin altering.
`category`	String	Category the segment has been assigned (if applicable).
`group`	String	Name of group the segment is assigned to.
`item`	String	Item value in the group the segment belongs to (if applicable).
`history`	Object	List of details about processing of this segment, including important status messages.
`widgetIds`	Array of String	Widget IDs if segment is used in CCE.
`cost`	Number	Pre-evaluated cost of the segment by the platform. Please note that for certain segments the cost can be unevaluated and hence unavailable, in which case in order to evaluate the cost, the /segment/validate API must be used instead.
`lastUploaded`	String	The time the segment was last uploaded.
`expirationDate`	String	The expiration date which shows when the current segment can be automatically deleted.
`contextCompatible`	String	True if the segment is compatible with contextual targeting.
`parentIds`	Array of String	Segment IDs of all the segments that reference current segment either directly or through other segments.
`directParentIds`	Array of String	Segment IDs of all the segments that reference current segment directly.
`includeUsersWithoutEvents`	boolean	Include users without events in export.

active flag explained

When the segment active flag is set to False, the segment has a limited functionality and can be used only

for reporting purposes:

in the family of traffic APIs e.g. /traffic as a part of a traffic filter;

as a building block for other segments:

as a part of a traffic filter in another segment.

When the segment active flag is set to True, the segment is enabled for a wider range of usages, such as user membership evaluation:

in the /profile/user/segment API;
in the Cxense Content API, namely in the [widget content settings "userSegment" condition](page://Content settings conditions#%22userSegment%22 (requires Cxense DMP%29);
in the lookalike modelling and so on.

Important notice

active segments usage is much more computationally expensive and a subject to necessary restrictions, such as of a total number of active segments and/or an individual computational cost of each segment.

Examples

Bash

$ python cx.py /segment/read
{
 "segments": [
 {
 "id": "00abfe6d40e8786c0ac583e141ccb3eeed740e59",
 "siteGroupId": "10501",
 "name": "Google-ref",
 "description": "Google as referrerhost",
 "filters": [
 {
 "type": "event",
 "group": "referrerHost",
 "item": "google.com"
 }
 ]
 },
 {
 "id": "4d9f373d752a1d1b77707a03316cb08a98debc44",
 "siteGroupId": "10501",
 "name": "Social referrer",
 "description": "Events with google or facebook as referrer",
 "filters": [
 {
 "type": "or",
 "filters": [
 {
 "type": "event",
 "group": "referrerHost",
 "item": "google.com"
 },
 {
 "type": "event",
 "group": "referrerHost",
 "item": "facebook.com"
 }
 ]
 }
 ]
 }
 ]
}

$ python cx.py /segment/read '{"siteGroupId":"10501"}'
{
 "segments": [
 {
 "id": "00abfe6d40e8786c0ac583e141ccb3eeed740e59",
 "siteGroupId": "10501",
 "name": "Google-ref",
 "description": "Google as referrerhost",
 "filters": [
 {
 "type": "event",
 "group": "referrerHost",
 "item": "google.com"
 }
 ]
 },
 {
 "id": "4d9f373d752a1d1b77707a03316cb08a98debc44",
 "siteGroupId": "10501",
 "name": "Social referrer",
 "description": "Events with google or facebook as referrer",
 "filters": [
 {
 "type": "or",
 "filters": [
 {
 "type": "event",
 "group": "referrerHost",
 "item": "google.com"
 },
 {
 "type": "event",
 "group": "referrerHost",
 "item": "facebook.com"
 }
 ]
 }
 ]
 }
 ]
}
$ python cx.py /segment/read '{"siteGroupIds":["10501", "10502"]}'
{
 "segments": [
 {
 "id": "00abfe6d40e8786c0ac583e141ccb3eeed740e59",
 "siteGroupId": "10501",
 "name": "Google-ref",
 "description": "Google as referrerhost",
 "filters": [
 {
 "type": "event",
 "group": "referrerHost",
 "item": "google.com"
 }
 ]
 },
 {
 "id": "4d9f373d752a1d1b77707a03316cb08a98debc44",
 "siteGroupId": "10501",
 "name": "Social referrer",
 "description": "Events with google or facebook as referrer",
 "filters": [
 {
 "type": "or",
 "filters": [
 {
 "type": "event",
 "group": "referrerHost",
 "item": "google.com"
 },
 {
 "type": "event",
 "group": "referrerHost",
 "item": "facebook.com"
 }
 ]
 }
 ]
 },
 {
 "id": "82d7s8gf29sn284gdc822hnf82jc933nc83n4892n",
 "siteGroupId": "10502",
 "name": "Facebook referrer",
 "description": "Facebook as referrerhost",
 "filters": [
 {
 "type": "event",
 "group": "referrerHost",
 "item": "facebook.com"
 }
 ]
 }
 ]
}
$ python cx.py /segment/read '{"id":"4d9f373d752a1d1b77707a03316cb08a98debc44"}'
{
 "segments": [
 {
 "id": "4d9f373d752a1d1b77707a03316cb08a98debc44",
 "siteGroupId": "10501",
 "name": "Social referrer",
 "description": "Events with google or facebook as referrer",
 "filters": [
 {
 "type": "or",
 "filters": [
 {
 "type": "event",
 "group": "referrerHost",
 "item": "google.com"
 },
 {
 "type": "event",
 "group": "referrerHost",
 "item": "facebook.com"
 }
 ]
 }
 ],
 "history": [
 {
 "time": 1582533978,
 "timeString": "2020-02-24T08:46:18.000Z",
 "status": "OK",
 "message": "Evaluated successfully"
 },
 {
 "time": 1582515172,
 "timeString": "2020-02-24T03:32:52.000Z",
 "status": "OK",
 "message": "Evaluated successfully"
 },
 {
 "time": 1582498127,
 "timeString": "2020-02-23T22:48:47.000Z",
 "status": "OK",
 "message": "Evaluated successfully"
 },
 {
 "time": 1582484233,
 "timeString": "2020-02-23T18:57:13.000Z",
 "status": "OK",
 "message": "Evaluated successfully"
 },
 {
 "time": 1582470378,
 "timeString": "2020-02-23T15:06:18.000Z",
 "status": "OK",
 "message": "Evaluated successfully"
 }
 ]
 }
 ]
}

$ python cx.py /segment/read '{"siteGroupId":"9222357704374132875", "annotations":[{"key":"maintainer","value":"segment-guy@example.com"}]}'
{
 "segments": [
 {
 "id": "1y2f0yp6cpj15",
 "siteGroupId": "9222357704374132875",
 "name": "mySegment",
 "description": "descriptive description",
 "filters": [
 {
 "start": "-1d",
 "stop": "-0d",
 "type": "time",
 "filter": {
 "type": "and",
 "filters": [
 {
 "type": "event",
 "group": "referrerUrl",
 "item": "https://cxense.com/test29"
 }
 ]
 }
 }
 ],
 "annotations": [
 {
 "key": "maintainer",
 "value": "segment-guy@example.com"
 }
 ],
 "active": false
 }
 ]
}
$ python cx.py /segment/read '{}'
[
 {
 "id": "1y2i99cplruxw",
 "name": "Test name",
 "description": "Test desc",
 "siteGroupId": "9222676619387915874",
 "filters": [
 {
 "tree": {
 "or": [
 {
 "segmentId": "1y2ibz99uwl70"
 },
 {
 "segmentId": "1y2ibz99uwl71"
 }
 ]
 }
 }
 ],
 "type": "combined"
 },
 {
 "id": "1y2i60cpkryxw",
 "name": "Test name",
 "description": "Test desc",
 "siteGroupId": "9222676619387915873",
 "filters": [
 {
 "tree": {
 "or": [
 {
 "segmentId": "1y2f0yp6cpj15"
 },
 {
 "segmentId": "1y2ibz99uwl72"
 }
 ]
 }
 }
 ],
 "type": "combined"
 }
]

Last updated: November 25, 2025