/segment/create | Documentation

API call to create an audience segmentation rule.

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

Within the last 31 days segments can be formed from any traffic filter. For periods older than the last 31 days, segments can be formed only when the following conditions are met:

All sites in the site group are configured for long term storage (LTS) with a period equal to or exceeding the segment period.
Explode users / user having filters can only be used for single-site groups.

Request

The request object has the following fields:

Name	Type	Required	Description
`siteGroupId`	String	Yes	The site group identifier to store the segmentation rule under.
`name`	String	Yes	Segment name. Maximum 250 characters.
`description`	String	No	Segment description. Maximum 250 characters.
`type`	String	Defaults to `traffic`	The type of the segment, and must be either `traffic` (the default), `external` or `dmp`. A `traffic` segment has members derived from a traffic filter, while a `external` segment receives members using /segment/data/update . A `dmp` segment is a segment that extracts members by evaluating dmp event filter. It's not possible to change the type of a segment.
`filters`	Array of Object	For type `traffic`	A list of filters that define a subset of the audience. The filter syntax is documented here . Note that the segment should include a time-filter to specify the length of time of event traffic to use as basis for the segment. If not, the time period the segment covers is 24 hours. The maximum time period is 31 days, unless the sites are configured for long term storage (LTS) (see the warning above).
`annotations`	Array of Object	No	A list of key/value pairs that can be used to look up the segment (see /segment/read ).
`active`	boolean	No	Set to True to enable the segment for active usage. Explained here .
`internal`	boolean	No	Set to True to make the segment internal to protect from nonadmin altering.
`group`	String	No	Name of the segment group to assign this segment to
`expirationDate`	Number	No	The expiration date which shows when the current segment can be automatically deleted.
`includeUsersWithoutEvents`	boolean	No	Include users without events in export.

Response

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

Name	Type	Description
`id`	String	The 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 here .
`group`	String	Assigned group name
`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.
`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.

Examples

Bash

$ python cx.py /segment/create '{"siteGroupId":"10501", "name":"Google-referrer", "description":"Events with google as referrer", "filters":[{"type":"time", "start":"-2d", "filter":{"type":"event", "group":"referrerHost", "item":"google.com"}}]}'
{
 "id": "8kwfp77cuw474p",
 "siteGroupId": "10501",
 "name": "Google-referrer",
 "description": "Events with google as referrer",
 "filters": [
 {
 "type": "time",
 "start":"-2d",
 "filters": [
 {
 "type": "event",
 "group": "referrerHost",
 "item": "google.com"
 }
 ]
 }
 ]
}

$ python cx.py /segment/create '{"siteGroupId":"10501", "name":"DMP", "description":"User Dmp Events", "type":"dmp", filters":[{"type":"user","having":{"min":1,"filter":{"type":"dmp-event","group":"origin","item":"user-filtering"}}}]}'
{
 "id": "8kwfp77cuw474l",
 "siteGroupId": "10501",
 "name": "DMP",
 "description": "User Dmp Events",
 "filters": [
 {
 "type": "user",
 "having": {
 "min": 1,
 "filter": {
 "type": "dmp-event",
 "group": "origin",
 "item":"user-filtering"
 }
 }
 }
 ]
}
$ python cx.py /segment/create '{"siteGroupId":"9222693460714263881","name":"Combined Segment","description":"Test description","type":"combined","filters":[{"type":"composition","tree":{"or":[{"segmentId":"1y2ibz9icng3w"},{"segmentId":"1y2ibz9icng3x"}]}}]}'

{
 "id": "1y2ibz9icng3y",
 "siteGroupId": "9222693460714263881",
 "name": "Combined Segment",
 "description": "Test description",
 "filters": [
 {
 "type": "composition",
 "tree": {
 "or": [
 {
 "segmentId": "1y2ibz9icng3w"
 },
 {
 "segmentId": "1y2ibz9icng3x"
 }
 ]
 }
 }
 ]
}

Last updated: November 25, 2025