/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 `user`	The type of the segment: `user` (the default), `external`, `contextual` or `combined`. A `user` segment has members derived from filters, while an `external` segment receives members using /segment/data/update . The legacy values `traffic`, `dmp`, `recs`, `conversion` and `propensity` are accepted and stored as `user`; use a context filter to pin the event context. The type of an existing segment can be changed with /segment/update .
`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.
`includeBots`	boolean	No	Bot traffic is excluded from the segment by default; set to `true` to keep bot traffic in the segment. Defaults to `false`. The default exclusion removes bot events, so a user with both bot and non-bot events stays in the segment; only users whose events are all bot-flagged are excluded. Applies to `traffic` and `user` segments that resolve to the traffic context. Has no effect on other segment types, nor on a segment whose filter is context compatible (content keyword and page filters only) — excluding bots requires event data, which would make such a segment unusable for contextual targeting. An inapplicable flag is stored but inert; it takes effect if the segment's filters are later changed to a shape the exclusion applies to. Bot exclusion applies if any segment in a reference chain excludes bots, so `includeBots: true` on a segment that references a bot-excluding segment does not re-admit bots.

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 `user`, `external`, `contextual` 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.
`includeBots`	boolean	Bot traffic is excluded from the segment by default; set to `true` to keep bot traffic in the segment. Defaults to `false`. The default exclusion removes bot events, so a user with both bot and non-bot events stays in the segment; only users whose events are all bot-flagged are excluded. Applies to `traffic` and `user` segments that resolve to the traffic context. Has no effect on other segment types, nor on a segment whose filter is context compatible (content keyword and page filters only) — excluding bots requires event data, which would make such a segment unusable for contextual targeting. An inapplicable flag is stored but inert; it takes effect if the segment's filters are later changed to a shape the exclusion applies to. Bot exclusion applies if any segment in a reference chain excludes bots, so `includeBots: true` on a segment that references a bot-excluding segment does not re-admit bots.

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: September 29, 2026