---
title: Perform a combinedData request
slug: '2672'
canonical_url: https://docs.coveo.com/en/2672/
collection: coveo-analytics
source_format: adoc
---
# Perform a combinedData request
The Usage Analytics Read API `stats/combinedData` endpoint allows you to retrieve [metric](https://docs.coveo.com/en/263/) values for combinations of selected [dimensions](https://docs.coveo.com/en/258/) (see [`/v15/stats/combinedData`](https://platform.cloud.coveo.com/docs?urls.primaryName=Usage%20Analytics%20Read#/Statistics%20API%20-%20Version%2015/get%5F%5Fv15_stats_combinedData)).

A typical situation in which you would want to use this endpoint is to leverage such [metrics](https://docs.coveo.com/en/263/) in your own application (that is, without going through the [Coveo Administration Console](https://docs.coveo.com/en/183/)).
This article explains how to make requests to do so.

> **Notes**
>
> * Search integrations with Coveo typically rely on the Administration Console [reports](https://docs.coveo.com/en/266/) rather than on the Coveo UA Read API directly (see [Coveo Analytics reports](https://docs.coveo.com/en/1674/)).
> 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:
>  
> ```http
GET https://platformhipaa.cloud.coveo.com/rest/v15/metrics?org=myOrg HTTP/1.1
```

## Example of a combinedData request

For every [origin level 1](https://docs.coveo.com/en/1337/), you want to know the daily number of [queries](https://docs.coveo.com/en/231/) and the daily number of [items](https://docs.coveo.com/en/210/) that were viewed during a given period of time.
You make a request to the `stats/combinedData` endpoint with the [dimensions](https://docs.coveo.com/en/258/) `[originLevel1](https://docs.coveo.com/en/1337/)` and `actionDayOfYear`, and with the [metrics](https://docs.coveo.com/en/263/) `PerformSearch` and `DocumentView` (see [`d`](#d-string) and [`m`](#m-string)).
You also request that results be sorted by day (see [`s`](#s-string)).

```http
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](https://en.wikipedia.org/wiki/Unix_time)), the [service](https://docs.coveo.com/en/2821/) returns the number of [events](https://docs.coveo.com/en/260/) which fall under the `PerformSearch` category.
They also return the number of [events](https://docs.coveo.com/en/260/) which fall under the `DocumentView` category.

**200 OK response body (excerpt)**

```json
{
  "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](https://docs.coveo.com/en/2821/) calculates the `PerformSearch` [metric](https://docs.coveo.com/en/263/) 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](https://docs.coveo.com/en/210/) 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](https://docs.coveo.com/en/2821/) must include an `Authorization` header with a valid access token (that is, an API key or OAuth2 token):

```http
Authorization: Bearer <token>
```

To make requests to the UA Read `stats/combinedData` endpoint, the `<token>` must grant the **Analytics - Analytics data - View** [privilege](https://docs.coveo.com/en/228/) in the target Coveo [organization](https://docs.coveo.com/en/185/) (see [Create an API key](https://docs.coveo.com/en/1718#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](https://docs.coveo.com/en/231/) parameter, as `OAuth2` tokens are platform-wide and can therefore allow access to more than one Coveo [organization](https://docs.coveo.com/en/185/).
> Otherwise, the `org` value is extracted from the API key.
> 
> `org` (string);
> the ID of the [organization](https://docs.coveo.com/en/185/).
> 
> For example:
> 
> ```text
myorg6j53h4
```

## Making a request

**Example**

**A `combinedData` request where only the required query parameters are specified**

```http
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](https://en.wikipedia.org/wiki/Percent-encoding)).
> 
> For example, after you URL-encode the previous request, it becomes the following:
> 
> ```http
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^`](https://en.wikipedia.org/wiki/ISO_8601)).

**Example**

[,text]
```
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^`](https://en.wikipedia.org/wiki/ISO_8601)).

**Example**

[,text]
```
2019-02-05T15:20:20.266Z
```

#### `m` (string)

The [metric](https://docs.coveo.com/en/263/) to fetch.

To fetch several [metrics](https://docs.coveo.com/en/263/), send several `m` [query](https://docs.coveo.com/en/231/) parameters.

**Example**

To fetch [metrics](https://docs.coveo.com/en/263/) `PerformSearch` and `DocumentView`, append the following to your [query](https://docs.coveo.com/en/231/) string:

```text
&m=PerformSearch&m=DocumentView
```

> **Note**
>
> You can retrieve the exhaustive list of [metrics](https://docs.coveo.com/en/263/) available in your [organization](https://docs.coveo.com/en/185/) by making a request to the `metrics` endpoint (see [List Metrics](https://docs.coveo.com/en/2862/)).

#### `d` (string)

The [dimension](https://docs.coveo.com/en/258/) to fetch.

To fetch several [dimensions](https://docs.coveo.com/en/258/), send several `d` [query](https://docs.coveo.com/en/231/) parameters.

**Example**

To fetch [dimensions](https://docs.coveo.com/en/258/) `[originLevel1](https://docs.coveo.com/en/1337/)` and `actionDayOfYear`, append the following to your [query](https://docs.coveo.com/en/231/) string:

```text
&d=originLevel1&d=actionDayOfYear
```

> **Note**
>
> You can retrieve the exhaustive list of [dimensions](https://docs.coveo.com/en/258/) available in your [organization](https://docs.coveo.com/en/185/) by navigating to the [**Dimensions**](https://platform.cloud.coveo.com/admin/#/orgid/usage/dimensions/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/usage/dimensions/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/usage/dimensions/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/usage/dimensions/)) page of the [Coveo Administration Console](https://docs.coveo.com/en/183/) (see [Manage dimensions on custom metadata](https://docs.coveo.com/en/1522/)).
> 
> Alternatively, you can make a request to the `dimensions` endpoint (see [List dimensions](https://docs.coveo.com/en/2861/)).

### Optional query parameters

#### `tz` (string)

The timezone to map the [`from`](#from-string) and [`to`](#to-string) arguments into (`+/-hh:mm` or [IANA TZDB](https://en.wikipedia.org/wiki/Tz_database) format).

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

**Examples**

* {blank}

```text
America/Montreal
```

* {blank}

```text
+01:00
```

#### `f` (string)

The [filter](https://docs.coveo.com/en/2736/) to apply to the [event](https://docs.coveo.com/en/260/) [dimensions](https://docs.coveo.com/en/258/) (analogous to the SQL `WHERE` command).
If you send many `f` [query](https://docs.coveo.com/en/231/) parameters, the [service](https://docs.coveo.com/en/2821/) joins them with the `AND` operator.

You can define an `f` argument with the [Read filter syntax](https://docs.coveo.com/en/2727/).
You can also use preexisting [named filters](https://docs.coveo.com/en/264/) by preceding them by the `$` character.

**Examples**

* {blank}

```text
$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](https://docs.coveo.com/en/1990/)).
> 
> Alternatively, you can make a request to the `filters/reporting` endpoint (see [List Named Filters](https://docs.coveo.com/en/2860/)).

#### `fm` (string)

The [filter](https://docs.coveo.com/en/2736/) to apply to the [event](https://docs.coveo.com/en/260/) [metrics](https://docs.coveo.com/en/263/) (analogous to the SQL `WHERE` command).
If you send many `fm` [query](https://docs.coveo.com/en/231/) parameters, the [service](https://docs.coveo.com/en/2821/) joins them with the `AND` operator.

The [filter](https://docs.coveo.com/en/2736/) must respect the [Read filter syntax](https://docs.coveo.com/en/2727/).

**Example**

[,text]
```
documentView<1000
```

#### `s` (string)

The name of the [field](https://docs.coveo.com/en/200/) to order the results by (analogous to the SQL `ORDER BY` command).
Must be a [dimension](https://docs.coveo.com/en/258/) or [metric](https://docs.coveo.com/en/263/) specified in the [`m`](#m-string) or the [`d`](#d-string) parameter.

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

**Example**

[,text]
```
documentView
```

#### `p` (integer)

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

Default value is `1`.

**Example**

[,text]
```
2
```

#### `n` (integer)

The number of results to include per results page.

Default value is `10`.

**Example**

[,text]
```
20
```

#### `asc` (Boolean)

Whether to sort results by ascending order.

Default value is `true`.

**Example**

[,text]
```
false
```

#### `includeMetadata` (Boolean)

Whether to include [metadata](https://docs.coveo.com/en/218/) regarding the results, namely total and unique counts.
Only applicable when [format](#format-string) is set to JSON

Default value is `true`.

**Example**

[,text]
```
false
```

#### `format` (string)

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

Default value is `JSON`.

**Example**

[,text]
```
CSV
```

#### `bindOnLastSearch` (Boolean)

Whether to establish the relationship between [events](https://docs.coveo.com/en/260/) using the `lastSearchId` or the `visitId`.

Default value is `true`.

**Example**

In a support interface, you log a custom [event](https://docs.coveo.com/en/260/) with a custom [data](https://docs.coveo.com/en/259/) [field](https://docs.coveo.com/en/200/) `c_caseid` whenever a support case is created.
You've created a custom [dimension](https://docs.coveo.com/en/258/) on `c_caseid` (see [Manage dimensions on custom metadata](https://docs.coveo.com/en/1522/)).
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](https://docs.coveo.com/en/258/) `c_caseid` and [metric](https://docs.coveo.com/en/263/) `performSearch`, with `bindOnLastSearch` set to `false`.

```http
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](https://docs.coveo.com/en/2821/) returns the number of search [events](https://docs.coveo.com/en/260/) (`PerformSearch`) in the same [visit](https://docs.coveo.com/en/271/).

```json
{
  "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](https://docs.coveo.com/en/2821/) would have returned the number of search [events](https://docs.coveo.com/en/260/) that immediately preceded the case creation, namely `0` or `1`.

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