/traffic/user | Documentation

This API returns a list of user identifiers that have events matching the specified filter. Only users registered with an external customer-specified identity are included in the result. These identities can be added using the addExternalId() Javascript call, or through /profile/user/external/link/update . See External user identifiers for more information about using external customer identifiers with the Cxense's APIs.

The user must be authenticated and have read permissions to referenced site groups/sites.

The maximum number of unique external customers returned per query is currently 50 000. To return more than this, it is advisable to decompose the query into multiple queries with smaller result sets.

Current aggregation period and filter restrictions are as follows:

Period	Groups available	Fields available	Filters available	Notes
Last 31 days or less	All	`events, uniqueUsers`	All
More than 31 days ago without long term storage	None	None	None	The data is unavailable for periods over 31 days, unless the sites are configured with long term support.
More than 31 days ago with long term storage	All	`events`, `uniqueUsers`	All	The `explodeUsers` filter and `uniqueUsers` field can be used only for a single site, i.e., when the number of sites is `1`.

Request

Identical to /traffic/event , except for:

Name	Type	Required	Description
fields	Array of String	No	The metrics to aggregate as specified under Fields at /traffic . This API call only supports aggregation of `events` and `uniqueUsers` .
`groups`	Array of String	No	List of external customer identifier types to return results for. In the case of multiple identifiers specified, and where the same user is registered under more than one of the external customer identifier, a separate entry is returned for the same user for each of the external customer identifiers. The Cxense-specific identifier type `cx` is not supported as a return format.
`count`	Integer	No	The maximum number of items to return for each group. The default value is 10, the maximum value is 50 000.
`orderBy`	String	No	Only events and unique users are valid as ordering criteria.

Note that uniqueUsers reflects how many different Cxense-specific identifiers were collected per external customer identifier, for example due to multiple devices or different browsers. For more information see the user identities demystification page. Furthermore, history aggregation (historyFields) is not supported for this API.

Response

Identical to /traffic/event, except that title is not available. See also example below.

Examples

In the following example we assume that 'cxd' is a registered external customer identifier type.

Bash

$ python cx.py /traffic/user '{"siteId":"12345", "fields":["uniqueUsers"], "start":"-1d"}'
{
 "start": 1416317631,
 "stop": 1416404031,
 "groups": [
 {
 "data": {
 "uniqueUsers": 7407,
 "events": 13565
 },
 "group": "cxd",
 "items": [
 {
 "item": "CXNEWS-EXTERNAL-001239",
 "data": {
 "uniqueUsers": 1,
 "events": 7
 }
 },
 {
 "item": "CXNEWS-EXTERNAL-003278",
 "data": {
 "uniqueUsers": 1,
 "events": 7
 }
 },
 {
 "item": "CXNEWS-EXTERNAL-006507",
 "data": {
 "uniqueUsers": 1,
 "events": 7
 }
 },
 {
 "item": "CXNEWS-EXTERNAL-009834",
 "data": {
 "uniqueUsers": 1,
 "events": 7
 }
 },
 {
 "item": "CXNEWS-EXTERNAL-000046",
 "data": {
 "uniqueUsers": 1,
 "events": 6
 }
 },
 {
 "item": "CXNEWS-EXTERNAL-000133",
 "data": {
 "uniqueUsers": 1,
 "events": 6
 }
 },
 {
 "item": "CXNEWS-EXTERNAL-000173",
 "data": {
 "uniqueUsers": 1,
 "events": 6
 }
 },
 {
 "item": "CXNEWS-EXTERNAL-000201",
 "data": {
 "uniqueUsers": 1,
 "events": 6
 }
 },
 {
 "item": "CXNEWS-EXTERNAL-000331",
 "data": {
 "uniqueUsers": 1,
 "events": 6
 }
 },
 {
 "item": "CXNEWS-EXTERNAL-000875",
 "data": {
 "uniqueUsers": 1,
 "events": 6
 }
 }
 ]
 }
 ]
}

Last updated: November 12, 2024