Perform a combinedData Request

This is for:

Business Analyst System Administrator

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

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 dimensions originLevel1 and actionDayOfYear, and with metrics PerformSearch and DocumentView (see d and m). You also request results be sorted by day (see s).

GET https://analytics.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 usage analytics events which fall under the PerformSearch category, as well as the number of usage analytics 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
    },
    ...
  ],
  ...
}

  • The way the Usage Analytics 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 above 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.

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

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

Authenticating

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

Authorization: Bearer <token>

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

If a Usage Analytics Read API request is authenticated using an OAuth2 token, you need to 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

A combinedData request where only the required query parameters are specified

GET https://analytics.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 **********-****-****-****-************

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

For example, after you URL-encode the above 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 **********-****-****-****-************

To make the examples in this article work in the Coveo HIPAA environment, replace platform by analyticshipaa in the example request headers.

For example:

GET https://analyticshipaa/rest/v15/metrics?org=myOrg HTTP/1.1

Required Query Parameters

from (string)

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

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).

2019-02-05T15:20:20.266Z

m (string)

The metric to fetch.

To fetch several metrics, send several m query parameters.

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

&m=PerformSearch&m=DocumentView

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.

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

&d=originLevel1&d=actionDayOfYear

You can retrieve the exhaustive list of dimensions available in your organization by navigating to the Dimensions 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 (i.e., Coordinated Universal Time).

  • 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.

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

    where EXCLUDE_PAGEVIEW_BOTS is a preexisting named filter.

  • Alternatively, you can send several f query parameters. I.e., 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.

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.

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.

documentView

p (integer)

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

Default value is 1.

2

n (integer)

The number of results to include per results page.

Default value is 10.

20

asc (Boolean)

Whether to sort results by ascending order.

Default value is true.

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.

false

format (string)

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

Default value is JSON.

CSV

bindOnLastSearch (Boolean)

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

Default value is true.

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://analytics.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, i.e., 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
    },
    ...
  ],
  ...
}