Segment Queries

Introduction to Segment Queries

The Segment Queries API is used to retrieve IDs of devices that meet certain criteria. The IDs can be internal Colocator IDs or an alias provided by the app developer. This can be done as a batch or as a callback. Segments must first be created via the Segment Filters API. Segment Queries should be used when you need to know individual IDs (for example, to send them a push message). If you are doing analysis on the number of devices that match a segment Analytics Queries should be used instead.


To get all the devices that match the given segment use the following API call:

POST /v2/segmentQuery/advanced/batch/{segmentId}

Additionally an alias can be specified. This allows the ID list returned to be an alias specified by the app instead of an internal Colocator ID:



Callbacks can be setup so that an API call is made to another system when a device meets the segment.

GET, PUT, POST and DELETE methods are available for /v2/segmentQuery/callbacks

Callback properties

idStringThe callback ID. This is not required (and will be ignored) on creation. It is used when updating callbacks.
nameStringThe name of the callback
callbackURLStringThe URL to POST to when a device meets the segment
trajectoryFilterIdStringThe ID of the segment in use
callbackStrategyStringThe callback can be made ONCE The first time the segment is met for each device ALL Every time the segment is met for each device SENDSPER Limited to a number of sends per period for each device
sendsPerNumberUsed with the SENDSPER callback strategy. The number of sends per the defined period
periodStringUsed with the SENDSPER callback strategy. The period that the sendsPer applies
activationTimeStringThe time in milliseconds since epoch that the callback should activate
deactivationTimeStringThe time in milliseconds since epoch that the callback should deactivate
stateStringACTIVE, INACTIVE or PAUSED. The callback will automatically change between ACTIVE and INACTIVE as the times stated. Changing the callback from ACTIVE to INACTIVE while it is in it’s active period will be ineffective (this is also true the other way around). A callback can be set to PAUSED while ACTIVE and ACTIVE while PAUSED
aliasStringThe key of the alias to return instead of the internal Colocator ID

Callbacks will return with a JSON body with one property, id. This will be an internal Colocator ID or an alias if defined in the callback.

There may be limits applied to how many callbacks can be active concurrently.