User Status Detail query

User Status Detail queries show the finest level of user activity. The query data reflects the user's Genesys Cloud presence as well as their ACD routing status at the individual status-change level.

Before diving too deep into the numbers, take a moment to make yourself familiar with the subtleties and distinctions between primary and secondary presence as well as ACD routing status.

A user status detail query provides a low-level view into all the status changes a user went through during a given interval. This is where you get the individual punch-in/punch-out style details and not the bird's eye view.

The syntax of this query conforms to the general template for detail record queries.

Responses to synchronous queries (not jobs), contain a totalHits parameter, representing the approximate total number of records matching the query. It is possible for a request to return fewer than totalHits records, because duplicates occasionally occur and are filtered out of the response. Total hits should be seen as an indicator of the order of magnitude of the number of matches and that's it.

User filters are limited to the userId dimension only. Presence filters and aggregations are limited to the systemPresence and organizationPresence dimension only. Routing status filters and aggregations are limited to the routingStatus dimension only. Intervals are limited to a duration not to exceed 7 days if you provide no filters and 31 days if you do provide filters.

When paging through user details, you may notice that pages may contain fewer than the requested page size entries. This happens due to limitations of the backend implementation when a user status spans multiple days. In this case, the user status is stored twice - once for the start day and once for the end day. If both days are in the query interval, both will be included in the results when paging through the database but then the redundant status entry will be dropped during postprocessing.

User Detail Record jobs are an alternate means of accessing the same data behind a User Detail Record query but in bulk. The data behind both is the same and the vast majority of the request/response payload is also the same.

Depending on your needs, one endpoint might standout as the obvious choice for you. It is also possible that you might need to employ both and to stitch results together.

The query endpoint is intended for users who need the most up-to-date data and they need a response to their query right now. The need for speed comes with limitations though. For example, you can query for data over shorter intervals and get fewer results per page. This endpoint is not intended for bulk export workloads.

This query is asking for specific presence and ACD routing status changes for two users (whose IDs are "0018052a-d9af-4dc2-9c0d-0e8406725982" and "00403044-6669-4c41-bc1e-f1dd8f2ee61e") on April 5, 2016. There are also filters included that restricts the query results to only shows presences whose primary/system value is "AVAILABLE" and routing statuses which are "OFF_QUEUE"--all other status changes will be omitted from the results. Finally, there is a field, labelled presenceAggregations, which adds in bonus data to the query results: up to the top 10 most frequent organization (secondary) presences found in the search results.

{
  "interval": "2016-04-05T07:00:00Z/2016-04-08T07:00:00Z",
  "userFilters": [
      {
        "type": "or",
        "predicates": [
            {
                "dimension": "userId",
                "value": "0018052a-d9af-4dc2-9c0d-0e8406725982"
            },
            {
                "dimension": "userId",
                "value": "00403044-6669-4c41-bc1e-f1dd8f2ee61e"
            }
        ]
      }
  ],
  "presenceFilters": [
      {
        "type": "or",
        "predicates": [
            {
                "dimension": "systemPresence",
                "value": "AVAILABLE"
            }
        ]
      }
  ],
  "routingStatusFilters": [
      {
        "type": "or",
        "predicates": [
            {
                "dimension": "routingStatus",
                "value": "OFF_QUEUE"
            }
        ]
      }
  ],
  "presenceAggregations": [
      {
          "type": "termFrequency",
          "dimension": "organizationPresenceId",
          "size": 10
      }
  ],
  "paging": {
    "pageSize": 10,
    "pageNumber": 1
  },
  "order": "asc"
}

For each of the two users queried for above, we see all of the presence and routing status changes (masked to our time interval) which matched our filter. Note that within each labeled user group, the presence changes and routing statuses are broken out into distinct sections and not merged onto a single timeline (so every user's results are distinct, as are their presence and routing statuses).

{
  "userDetails": [
    {
      "userId": "0018052a-d9af-4dc2-9c0d-0e8406725982",
      "primaryPresence": [
        {
          "startTime": "2016-04-07T14:00:44.462Z",
          "endTime": "2016-04-07T14:00:45.044Z",
          "systemPresence": "AVAILABLE",
          "organizationPresenceId": "6a3af858-942f-489d-9700-5f9bcdcdae9b"
        },
        {
          "startTime": "2016-04-07T15:20:10.376Z",
          "endTime": "2016-04-07T15:20:10.897Z",
          "systemPresence": "AVAILABLE",
          "organizationPresenceId": "6a3af858-942f-489d-9700-5f9bcdcdae9b"
        },
        {
          "startTime": "2016-04-07T17:02:55.533Z",
          "endTime": "2016-04-07T17:02:56.067Z",
          "systemPresence": "AVAILABLE",
          "organizationPresenceId": "6a3af858-942f-489d-9700-5f9bcdcdae9b"
        }
      ],
      "routingStatus": [
        {
          "startTime": "2016-04-07T14:00:44.539Z",
          "routingStatus": "OFF_QUEUE"
        }
      ]
    },
    {
      "userId": "00403044-6669-4c41-bc1e-f1dd8f2ee61e",
      "primaryPresence": [
        {
          "startTime": "2016-04-07T14:00:12.354Z",
          "endTime": "2016-04-07T14:00:12.912Z",
          "systemPresence": "AVAILABLE",
          "organizationPresenceId": "6a3af858-942f-489d-9700-5f9bcdcdae9b"
        },
        {
          "startTime": "2016-04-07T14:20:28.394Z",
          "endTime": "2016-04-07T14:20:28.936Z",
          "systemPresence": "AVAILABLE",
          "organizationPresenceId": "6a3af858-942f-489d-9700-5f9bcdcdae9b"
        },
        {
          "startTime": "2016-04-07T15:19:38.413Z",
          "endTime": "2016-04-07T15:19:39.023Z",
          "systemPresence": "AVAILABLE",
          "organizationPresenceId": "6a3af858-942f-489d-9700-5f9bcdcdae9b"
        },
        {
          "startTime": "2016-04-07T17:02:23.616Z",
          "endTime": "2016-04-07T17:02:24.174Z",
          "systemPresence": "AVAILABLE",
          "organizationPresenceId": "6a3af858-942f-489d-9700-5f9bcdcdae9b"
        }
      ],
      "routingStatus": [
        {
          "startTime": "2016-04-07T14:00:12.404Z",
          "routingStatus": "OFF_QUEUE"
        }
      ]
    }
  ],
  "aggregations": [
    {
      "type": "termFrequency",
      "dimension": "organizationPresenceId",
      "count": 7,
      "results": [
        {
          "count": 7,
          "value": "6a3af858-942f-489d-9700-5f9bcdcdae9b"
        }
      ]
    }
  ]
}