/segment/update | Documentation

API call to update an audience segmentation rule.

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

Request

The request object has the following fields:

Name	Type	Required	Description
id	String	Yes	Identifier for the audience segment rule to be updated.
name	String	No	Segment name. Maximum 32 characters.
description	String	No	Segment description. Maximum 250 characters.
filters	Array of Object	No	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 undefined. The maximum time period is 30 days.
annotations	Array of Object	No	A list of key/value pairs that can be used to look up the segment (see /segment/read ). Note that this overwrites the entire list of annotations. Incremental add/update of individual annotations is not supported. Make sure to supply the entire list of annotations for the segment whenever one of them is updated.
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.

Only the fields specified in the request will be updated.

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	Name of the segment group bind with specified segment
`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.

Examples

Bash

# Before:
$ python cx.py /segment/read '{"id":"ff50970350bcc43ea10c022018a28b33bf8a404a"}'
{
 "segments": [
 {
 "id": "ff50970350bcc43ea10c022018a28b33bf8a404a",
 "siteGroupId": "10501",
 "name": "Google-referrer",
 "description": "Events with google as referrer",
 "filters": [
 {
 "type": "event",
 "group": "referrerHost",
 "item": "google.com"
 }
 ]
 }
 ]
}
$ python cx.py /segment/update '{"id":"ff50970350bcc43ea10c022018a28b33bf8a404a", "name":"Social referrer", "description":"Events with google or facebook as referrer", "filters":[{"type":"time", "start":"-2d", "filter":{"type":"or", "filters":[{"type":"event", "group":"referrerHost", "item":"google.com"}, {"type":"event", "group":"referrerHost", "item":"facebook.com"}]}}]}'
{
 "id": "ff50970350bcc43ea10c022018a28b33bf8a404a",
 "siteGroupId": "10501",
 "name": "Social referrer",
 "description": "Events with google or facebook as referrer",
 "filters": [
 {
 "type": "time",
 "start": "-2d",
 "filter": {
 "type": "or",
 "filters": [
 {
 "type": "event",
 "group": "referrerHost",
 "item": "google.com"
 },
 {
 "type": "event",
 "group": "referrerHost",
 "item": "facebook.com"
 }
 ]
 }
 }
 ],
 "active": true
}

Last updated: November 25, 2025