Perform a combinedData request

This is for:

Business Analyst System Administrator

The Usage Analytics Read API stats/combinedData endpoint allows you to retrieve metric values for combinations of selected dimensions (see /v15/stats/combinedData).

A typical situation in which you would want to use this endpoint is to leverage such metrics in your own application (that is, without going through the Coveo Administration Console). This article explains how to make requests to do so.

Notes

  • Search integrations with Coveo typically rely on the Administration Console reports rather than on the Coveo UA Read API directly (see Coveo Analytics reports). This article is relevant only if your use case isn’t met by the Administration Console.

  • To make the examples in this article work in the Coveo HIPAA environment, replace platform with platformhipaa in the example request URL.

    For example:

    GET https://platformhipaa.cloud.coveo.com/rest/v15/metrics?org=myOrg HTTP/1.1

Example of a combinedData request

For every origin level 1, you want to know the daily number of queries and the daily number of items that were viewed during a given period of time. You make a request to the stats/combinedData endpoint with the dimensions originLevel1 and actionDayOfYear, and with the metrics PerformSearch and DocumentView (see d and m). You also request that results be sorted by day (see s).

GET https://platform.cloud.coveo.com/rest/ua/v15/stats/combinedData?from=2019-01-13T14:20:20.266Z&to=2019-02-13T15:20:20.266Z&d=originLevel1&d=actionDayOfYear&m=PerformSearch&m=DocumentView&s=actionDayOfYear HTTP/1.1

Authorization: Bearer **********-****-****-****-************

For every combination of originLevel1 and actionDayOfYear (in Unix time), the service returns the number of events which fall under the PerformSearch category. They also return the number of events which fall under the DocumentView category.

200 OK response body (excerpt)

{
  "combinations": [
    {
      "originLevel1": "CaseCreation",
      "actionDayOfYear": 1547337600000,
      "PerformSearch": 4513,
      "DocumentView": 827
    },
    {
      "originLevel1": "ExternalSearch",
      "actionDayOfYear": 1547337600000,
      "PerformSearch": 2153,
      "DocumentView": 85
    },
    {
      "originLevel1": "CaseCreation",
      "actionDayOfYear": 1547424000000,
      "PerformSearch": 5032,
      "DocumentView": 881
    },
    {
      "originLevel1": "ExternalSearch",
      "actionDayOfYear": 1547424000000,
      "PerformSearch": 2042,
      "DocumentView": 92
    },
    ...
  ],
  ...
}
Notes

  • The way the UA Read service calculates the PerformSearch metric differs from the one used to calculate the query count in the Settings section of the Coveo Administration Console.

  • In the previous example, the org query parameter isn’t included, since it’s extracted form the API key. If an OAuth2 token was used, the org query parameter would need to be included.

  • Requests that would cause the UA Read API to return more than 10,000 items in the response are rejected, returning a 400 - Parameter 'n' must be between 1 and 10000 error. If this happens, consider decreasing the scope of the request.

Authenticating

The UA Read API relies on the bearer HTTP authentication scheme. All HTTP requests made to the UA Read service must include an Authorization header with a valid access token (that is, an API key or OAuth2 token):

Authorization: Bearer <token>

To make requests to the UA Read stats/combinedData endpoint, the <token> must grant the Analytics - Analytics data - View privilege in the target Coveo organization (see Create an API key).

Note

If a UA Read API request is authenticated using an OAuth2 token, you must specify a value for the org query parameter, as OAuth2 tokens are platform-wide and can therefore allow access to more than one Coveo organization. Otherwise, the org value is extracted from the API key.

org (string); the ID of the organization.

For example:

myorg6j53h4

Making a request

Example

A combinedData request where only the required query parameters are specified

GET https://platform.cloud.coveo.com/rest/ua/v15/stats/combinedData?from=2018-02-05T14:20:20.266Z&to=2019-02-05T15:20:20.266Z&m=CustomEvent&d=c_facettitle HTTP/1.1

Authorization: Bearer **********-****-****-****-************
Important

Make sure that you URL-encode your requests (see Percent-encoding).

For example, after you URL-encode the previous request, it becomes the following:

GET https%3A%2F%2Fplatform.cloud.coveo.com%2Frest%2Fua%2Fv15%2Fstats%2FcombinedData%3Ffrom%3D2018-02-05T14%3A20%3A20.266Z%26to%3D2019-02-05T15%3A20%3A20.266Z%26m%3DCustomEvent%26d%3Dc_facettitle HTTP/1.1

Authorization: Bearer **********-****-****-****-************

Required query parameters

from (string)

The beginning date of the date range. ISO8601 format YYYY-MM-DDThh:mm:ss.sssZ (see ISO 8601^).

Example
2018-02-05T14:20:20.266Z

to (string)

The end date of the date range. ISO8601 format YYYY-MM-DDThh:mm:ss.sssZ (see ISO 8601^).

Example
2019-02-05T15:20:20.266Z

m (string)

The metric to fetch.

To fetch several metrics, send several m query parameters.

Example

To fetch metrics PerformSearch and DocumentView, append the following to your query string:

&m=PerformSearch&m=DocumentView
Note

You can retrieve the exhaustive list of metrics available in your organization by making a request to the metrics endpoint (see List Metrics).

d (string)

The dimension to fetch.

To fetch several dimensions, send several d query parameters.

Example

To fetch dimensions originLevel1 and actionDayOfYear, append the following to your query string:

&d=originLevel1&d=actionDayOfYear
Note

You can retrieve the exhaustive list of dimensions available in your organization by navigating to the Dimensions (platform-ca | platform-eu | platform-au) page of the Coveo Administration Console (see Manage dimensions on custom metadata).

Alternatively, you can make a request to the dimensions endpoint (see List dimensions).

Optional query parameters

tz (string)

The timezone to map the from and to arguments into (+/-hh:mm or IANA TZDB format).

Default value is Z (that is, Coordinated Universal Time).

Examples

  • America/Montreal

  • +01:00

f (string)

The filter to apply to the event dimensions (analogous to the SQL WHERE command). If you send many f query parameters, the service joins them with the AND operator.

You can define an f argument with the Read filter syntax. You can also use preexisting named filters by preceding them by the $ character.

Examples

  • $EXCLUDE_PAGEVIEW_BOTS AND (customeventtype=='pageVisit')

    where EXCLUDE_PAGEVIEW_BOTS is a preexisting named filter.

  • Alternatively, you can send several f query parameters. In other words, appending &f=$EXCLUDE_PAGEVIEW_BOTS AND (customeventtype=='pageVisit') to your query string is equivalent to appending &f=$EXCLUDE_PAGEVIEW_BOTS&f=(customeventtype=='pageVisit') to your query string.

Note

You can retrieve the exhaustive list of named filters available in your organization by navigating to the Named Filters page of the Coveo Administration Console (see Manage Named Filters).

Alternatively, you can make a request to the filters/reporting endpoint (see List Named Filters).

fm (string)

The filter to apply to the event metrics (analogous to the SQL WHERE command). If you send many fm query parameters, the service joins them with the AND operator.

The filter must respect the Read filter syntax.

Example
documentView<1000

s (string)

The name of the field to order the results by (analogous to the SQL ORDER BY command). Must be a dimension or metric specified in the m or the d parameter.

If no value is provided, the result ordering is unpredictable.

Example
documentView

p (integer)

The 1-based number of the results page to access.

Default value is 1.

Example
2

n (integer)

The number of results to include per results page.

Default value is 10.

Example
20

asc (Boolean)

Whether to sort results by ascending order.

Default value is true.

Example
false

includeMetadata (Boolean)

Whether to include metadata regarding the results, namely total and unique counts. Only applicable when format is set to JSON

Default value is true.

Example
false

format (string)

The format of the response. Possible values are JSON and CSV.

Default value is JSON.

Example
CSV

bindOnLastSearch (Boolean)

Whether to establish the relationship between events using the lastSearchId or the visitId.

Default value is true.

Example

In a support interface, you log a custom event with a custom data field c_caseid whenever a support case is created. You’ve created a custom dimension on c_caseid (see Manage dimensions on custom metadata). You want to know how many queries preceded the creation of each support case.

You send a request to the stats/combinedData endpoint on dimension c_caseid and metric performSearch, with bindOnLastSearch set to false.

GET https://platform.cloud.coveo.com/rest/ua/v15/stats/combinedData?from=2019-01-13T14:20:20.266Z&to=2019-02-13T15:20:20.266Z&d=c_caseid&m=PerformSearch&bindOnLastSearch=false HTTP/1.1

Content-Type: application/json
Authorization: Bearer **********-****-****-****-************

For every case created (c_caseid), the service returns the number of search events (PerformSearch) in the same visit.

{
  "combinations": [
    {
      "c_caseid": "5000d00001O0PxBAAV",
      "PerformSearch": 5
    },
    {
      "c_caseid": "5000d00001P9fXJAAZ",
      "PerformSearch": 3
    },
    ...
  ],
  ...
}

If bindOnLastSearch had been left to the default value, that is, true, the service would have returned the number of search events that immediately preceded the case creation, namely 0 or 1.

{
  "combinations": [
    {
      "c_caseid": "5000d00001O0PxBAAV",
      "PerformSearch": 1
    },
    {
      "c_caseid": "5000d00002P3fUZEEZ",
      "PerformSearch": 0
    },
    ...
  ],
  ...
}