# Queries with their metrics

`POST /analytics/v1/searches/queries`

What people search for, query by query.

For the queries without results, add `metric_filters: {"searches_without_results": {"gt": 0}}`.

## Request example

```bash
curl --request POST \
  --url 'https://api.eu1.luigisbox.ai/analytics/v1/searches/queries?channel_ids=<channel_ids>&page=1&size=20' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "attribution_model": "last_touch",
  "date_range": {
    "date_from": "2026-04-15T12:00:00Z",
    "date_to": "2026-04-15T12:00:00Z"
  },
  "filters": {
    "$and": [
      {}
    ],
    "$not": {},
    "$or": [
      {}
    ]
  },
  "group_by": [],
  "metric_filters": {
    "$and": [
      {}
    ],
    "$not": {},
    "$or": [
      {}
    ]
  },
  "metrics": [
    "users"
  ],
  "sort": {
    "direction": "desc",
    "field": "searches"
  },
  "touchpoints": [
    "autocomplete"
  ]
}'
```

## Query Parameters

| Name | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `channel_ids` | `Array<string>` | Yes | One or more channel ids to aggregate over. Provide as repeated query parameters (``?channel_ids=A&channel_ids=B``). | >= 1 items |
| `page` | `integer` | No | 1-based page number. | >= 1 |
| `size` | `integer` | No | Number of items per page. | >= 1; <= 100 |

## Request Body

**Required.**

### application/json

Schema: `object`

#### Attributes

| Attribute | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `attribution_model` | `string` | No | Which of the lists that showed an item is credited with an interaction on it; only `last_touch`, the last of them, is recorded today. | allowed values: last_touch |
| `date_range` | `object` | Yes | The time range of the report. | — |
| `date_range.date_from` | `string` | Yes | Start, inclusive. | format: date-time |
| `date_range.date_to` | `string` | Yes | End, exclusive. | format: date-time |
| `filters` | `anyOf(oneOf(object, object), null)` | No | Which rows are counted; every row when left out. `followed_by_search` holds on an autocomplete list the shopper submitted as a search, and never on a `serp` list. At most 100 conditions, in groups nested at most 10 deep — conditions are counted and the groups holding them are not. A tree past either is a `422` of type `filter_too_complex`. | — |
| `filters.$and` | `Array<oneOf(object, object)>` | No | Nodes that must all match. | >= 1 items |
| `filters.$not` | `oneOf(object, object)` | No | A node that must not match. | — |
| `filters.$or` | `Array<oneOf(object, object)>` | No | Nodes of which at least one must match. | >= 1 items |
| `filters.applied_filter` | `object` | No | Operators on one text field. | — |
| `filters.applied_filter.eq` | `string` | No | Equal to. | — |
| `filters.applied_filter.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `filters.applied_filter.in` | `Array<string>` | No | One of. | >= 1 items; <= 100 items |
| `filters.applied_filter.matches` | `string` | No | Contains this text. | >= 1 characters |
| `filters.applied_filter.neq` | `string` | No | Not equal to. | — |
| `filters.applied_filter.not_in` | `Array<string>` | No | None of. | >= 1 items; <= 100 items |
| `filters.consent_granted` | `object` | No | Operators on one true-or-false field. | — |
| `filters.consent_granted.eq` | `boolean` | No | Equal to. | — |
| `filters.device` | `object` | No | Operators on one text field. | — |
| `filters.device.eq` | `string` | No | Equal to. | — |
| `filters.device.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `filters.device.in` | `Array<string>` | No | One of. | >= 1 items; <= 100 items |
| `filters.device.matches` | `string` | No | Contains this text. | >= 1 characters |
| `filters.device.neq` | `string` | No | Not equal to. | — |
| `filters.device.not_in` | `Array<string>` | No | None of. | >= 1 items; <= 100 items |
| `filters.external_ab_test_variant` | `object` | No | Operators on one text field. | — |
| `filters.external_ab_test_variant.eq` | `string` | No | Equal to. | — |
| `filters.external_ab_test_variant.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `filters.external_ab_test_variant.in` | `Array<string>` | No | One of. | >= 1 items; <= 100 items |
| `filters.external_ab_test_variant.matches` | `string` | No | Contains this text. | >= 1 characters |
| `filters.external_ab_test_variant.neq` | `string` | No | Not equal to. | — |
| `filters.external_ab_test_variant.not_in` | `Array<string>` | No | None of. | >= 1 items; <= 100 items |
| `filters.filtered` | `object` | No | Operators on one true-or-false field. | — |
| `filters.filtered.eq` | `boolean` | No | Equal to. | — |
| `filters.followed_by_search` | `object` | No | Operators on one true-or-false field. | — |
| `filters.followed_by_search.eq` | `boolean` | No | Equal to. | — |
| `filters.identity` | `object` | No | Operators on one text field. | — |
| `filters.identity.eq` | `string` | No | Equal to. | — |
| `filters.identity.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `filters.identity.in` | `Array<string>` | No | One of. | >= 1 items; <= 100 items |
| `filters.identity.matches` | `string` | No | Contains this text. | >= 1 characters |
| `filters.identity.neq` | `string` | No | Not equal to. | — |
| `filters.identity.not_in` | `Array<string>` | No | None of. | >= 1 items; <= 100 items |
| `filters.internal_ab_test_id` | `object` | No | Operators on one text field. | — |
| `filters.internal_ab_test_id.eq` | `string` | No | Equal to. | — |
| `filters.internal_ab_test_id.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `filters.internal_ab_test_id.in` | `Array<string>` | No | One of. | >= 1 items; <= 100 items |
| `filters.internal_ab_test_id.matches` | `string` | No | Contains this text. | >= 1 characters |
| `filters.internal_ab_test_id.neq` | `string` | No | Not equal to. | — |
| `filters.internal_ab_test_id.not_in` | `Array<string>` | No | None of. | >= 1 items; <= 100 items |
| `filters.internal_ab_test_variant` | `object` | No | Operators on one text field. | — |
| `filters.internal_ab_test_variant.eq` | `string` | No | Equal to. | — |
| `filters.internal_ab_test_variant.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `filters.internal_ab_test_variant.in` | `Array<string>` | No | One of. | >= 1 items; <= 100 items |
| `filters.internal_ab_test_variant.matches` | `string` | No | Contains this text. | >= 1 characters |
| `filters.internal_ab_test_variant.neq` | `string` | No | Not equal to. | — |
| `filters.internal_ab_test_variant.not_in` | `Array<string>` | No | None of. | >= 1 items; <= 100 items |
| `filters.landing_page` | `object` | No | Operators on one text field. | — |
| `filters.landing_page.eq` | `string` | No | Equal to. | — |
| `filters.landing_page.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `filters.landing_page.in` | `Array<string>` | No | One of. | >= 1 items; <= 100 items |
| `filters.landing_page.matches` | `string` | No | Contains this text. | >= 1 characters |
| `filters.landing_page.neq` | `string` | No | Not equal to. | — |
| `filters.landing_page.not_in` | `Array<string>` | No | None of. | >= 1 items; <= 100 items |
| `filters.landing_page_host` | `object` | No | Operators on one text field. | — |
| `filters.landing_page_host.eq` | `string` | No | Equal to. | — |
| `filters.landing_page_host.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `filters.landing_page_host.in` | `Array<string>` | No | One of. | >= 1 items; <= 100 items |
| `filters.landing_page_host.matches` | `string` | No | Contains this text. | >= 1 characters |
| `filters.landing_page_host.neq` | `string` | No | Not equal to. | — |
| `filters.landing_page_host.not_in` | `Array<string>` | No | None of. | >= 1 items; <= 100 items |
| `filters.personalized` | `object` | No | Operators on one true-or-false field. | — |
| `filters.personalized.eq` | `boolean` | No | Equal to. | — |
| `filters.platform` | `object` | No | Operators on one text field. | — |
| `filters.platform.eq` | `string` | No | Equal to. | — |
| `filters.platform.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `filters.platform.in` | `Array<string>` | No | One of. | >= 1 items; <= 100 items |
| `filters.platform.matches` | `string` | No | Contains this text. | >= 1 characters |
| `filters.platform.neq` | `string` | No | Not equal to. | — |
| `filters.platform.not_in` | `Array<string>` | No | None of. | >= 1 items; <= 100 items |
| `filters.query` | `object` | No | Operators on one text field. | — |
| `filters.query.eq` | `string` | No | Equal to. | — |
| `filters.query.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `filters.query.in` | `Array<string>` | No | One of. | >= 1 items; <= 100 items |
| `filters.query.matches` | `string` | No | Contains this text. | >= 1 characters |
| `filters.query.neq` | `string` | No | Not equal to. | — |
| `filters.query.not_in` | `Array<string>` | No | None of. | >= 1 items; <= 100 items |
| `filters.redirected` | `object` | No | Operators on one true-or-false field. | — |
| `filters.redirected.eq` | `boolean` | No | Equal to. | — |
| `filters.result_type` | `object` | No | Operators on one text field. | — |
| `filters.result_type.eq` | `string` | No | Equal to. | — |
| `filters.result_type.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `filters.result_type.in` | `Array<string>` | No | One of. | >= 1 items; <= 100 items |
| `filters.result_type.matches` | `string` | No | Contains this text. | >= 1 characters |
| `filters.result_type.neq` | `string` | No | Not equal to. | — |
| `filters.result_type.not_in` | `Array<string>` | No | None of. | >= 1 items; <= 100 items |
| `filters.returning` | `object` | No | Operators on one true-or-false field. | — |
| `filters.returning.eq` | `boolean` | No | Equal to. | — |
| `filters.session_rank` | `object` | No | Operators on one whole-number field. | — |
| `filters.session_rank.eq` | `integer` | No | Equal to. | — |
| `filters.session_rank.gt` | `integer` | No | Greater than. | — |
| `filters.session_rank.gte` | `integer` | No | At least. | — |
| `filters.session_rank.in` | `Array<integer>` | No | One of. | >= 1 items; <= 100 items |
| `filters.session_rank.lt` | `integer` | No | Less than. | — |
| `filters.session_rank.lte` | `integer` | No | At most. | — |
| `filters.session_rank.neq` | `integer` | No | Not equal to. | — |
| `filters.session_rank.not_in` | `Array<integer>` | No | None of. | >= 1 items; <= 100 items |
| `filters.traffic_source` | `object` | No | Operators on how a session arrived. | — |
| `filters.traffic_source.eq` | `string` | No | Equal to. | allowed values: direct, paid, referral, llms |
| `filters.traffic_source.in` | `Array<string>` | No | One of. | >= 1 items; <= 100 items |
| `filters.traffic_source.neq` | `string` | No | Not equal to. | allowed values: direct, paid, referral, llms |
| `filters.traffic_source.not_in` | `Array<string>` | No | None of. | >= 1 items; <= 100 items |
| `filters.traffic_source_type` | `object` | No | Operators on one text field. | — |
| `filters.traffic_source_type.eq` | `string` | No | Equal to. | — |
| `filters.traffic_source_type.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `filters.traffic_source_type.in` | `Array<string>` | No | One of. | >= 1 items; <= 100 items |
| `filters.traffic_source_type.matches` | `string` | No | Contains this text. | >= 1 characters |
| `filters.traffic_source_type.neq` | `string` | No | Not equal to. | — |
| `filters.traffic_source_type.not_in` | `Array<string>` | No | None of. | >= 1 items; <= 100 items |
| `filters.url_host` | `object` | No | Operators on one text field. | — |
| `filters.url_host.eq` | `string` | No | Equal to. | — |
| `filters.url_host.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `filters.url_host.in` | `Array<string>` | No | One of. | >= 1 items; <= 100 items |
| `filters.url_host.matches` | `string` | No | Contains this text. | >= 1 characters |
| `filters.url_host.neq` | `string` | No | Not equal to. | — |
| `filters.url_host.not_in` | `Array<string>` | No | None of. | >= 1 items; <= 100 items |
| `filters.url_path` | `object` | No | Operators on one text field. | — |
| `filters.url_path.eq` | `string` | No | Equal to. | — |
| `filters.url_path.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `filters.url_path.in` | `Array<string>` | No | One of. | >= 1 items; <= 100 items |
| `filters.url_path.matches` | `string` | No | Contains this text. | >= 1 characters |
| `filters.url_path.neq` | `string` | No | Not equal to. | — |
| `filters.url_path.not_in` | `Array<string>` | No | None of. | >= 1 items; <= 100 items |
| `filters.*` | `object` | No | Operators on one text field. | — |
| `filters.*.eq` | `string` | No | Equal to. | — |
| `filters.*.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `filters.*.in` | `Array<string>` | No | One of. | >= 1 items; <= 100 items |
| `filters.*.matches` | `string` | No | Contains this text. | >= 1 characters |
| `filters.*.neq` | `string` | No | Not equal to. | — |
| `filters.*.not_in` | `Array<string>` | No | None of. | >= 1 items; <= 100 items |
| `group_by` | `Array<anyOf(string, string)>` | No | Fields that split every row, summary and series point, e.g. `["touchpoint", "device"]`: at most 2 besides `touchpoint`, which splits the `touchpoints`. At most one of `landing_page`, `url_path`, `url_params.*` and `context.*`; a summary or series holds at most 500 groups, and a session with several values of a key counts once in each of its groups. | <= 3 items |
| `metric_filters` | `anyOf(oneOf(object, object), null)` | No | Which rows are returned, by their metrics over `date_range`; naming a metric here does not add it to the response. At most 100 conditions, in groups nested at most 10 deep — conditions are counted and the groups holding them are not. A tree past either is a `422` of type `filter_too_complex`. | — |
| `metric_filters.$and` | `Array<oneOf(object, object)>` | No | Nodes that must all match. | >= 1 items |
| `metric_filters.$not` | `oneOf(object, object)` | No | A node that must not match. | — |
| `metric_filters.$or` | `Array<oneOf(object, object)>` | No | Nodes of which at least one must match. | >= 1 items |
| `metric_filters.attributed_average_order_value` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.attributed_average_order_value.eq` | `number` | No | Equal to. | — |
| `metric_filters.attributed_average_order_value.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.attributed_average_order_value.gt` | `number` | No | Greater than. | — |
| `metric_filters.attributed_average_order_value.gte` | `number` | No | At least. | — |
| `metric_filters.attributed_average_order_value.lt` | `number` | No | Less than. | — |
| `metric_filters.attributed_average_order_value.lte` | `number` | No | At most. | — |
| `metric_filters.attributed_average_order_value.neq` | `number` | No | Not equal to. | — |
| `metric_filters.attributed_cart_value` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.attributed_cart_value.eq` | `number` | No | Equal to. | — |
| `metric_filters.attributed_cart_value.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.attributed_cart_value.gt` | `number` | No | Greater than. | — |
| `metric_filters.attributed_cart_value.gte` | `number` | No | At least. | — |
| `metric_filters.attributed_cart_value.lt` | `number` | No | Less than. | — |
| `metric_filters.attributed_cart_value.lte` | `number` | No | At most. | — |
| `metric_filters.attributed_cart_value.neq` | `number` | No | Not equal to. | — |
| `metric_filters.attributed_key_events_1` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.attributed_key_events_1.eq` | `number` | No | Equal to. | — |
| `metric_filters.attributed_key_events_1.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.attributed_key_events_1.gt` | `number` | No | Greater than. | — |
| `metric_filters.attributed_key_events_1.gte` | `number` | No | At least. | — |
| `metric_filters.attributed_key_events_1.lt` | `number` | No | Less than. | — |
| `metric_filters.attributed_key_events_1.lte` | `number` | No | At most. | — |
| `metric_filters.attributed_key_events_1.neq` | `number` | No | Not equal to. | — |
| `metric_filters.attributed_key_events_1_rate` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.attributed_key_events_1_rate.eq` | `number` | No | Equal to. | — |
| `metric_filters.attributed_key_events_1_rate.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.attributed_key_events_1_rate.gt` | `number` | No | Greater than. | — |
| `metric_filters.attributed_key_events_1_rate.gte` | `number` | No | At least. | — |
| `metric_filters.attributed_key_events_1_rate.lt` | `number` | No | Less than. | — |
| `metric_filters.attributed_key_events_1_rate.lte` | `number` | No | At most. | — |
| `metric_filters.attributed_key_events_1_rate.neq` | `number` | No | Not equal to. | — |
| `metric_filters.attributed_key_events_2` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.attributed_key_events_2.eq` | `number` | No | Equal to. | — |
| `metric_filters.attributed_key_events_2.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.attributed_key_events_2.gt` | `number` | No | Greater than. | — |
| `metric_filters.attributed_key_events_2.gte` | `number` | No | At least. | — |
| `metric_filters.attributed_key_events_2.lt` | `number` | No | Less than. | — |
| `metric_filters.attributed_key_events_2.lte` | `number` | No | At most. | — |
| `metric_filters.attributed_key_events_2.neq` | `number` | No | Not equal to. | — |
| `metric_filters.attributed_key_events_2_rate` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.attributed_key_events_2_rate.eq` | `number` | No | Equal to. | — |
| `metric_filters.attributed_key_events_2_rate.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.attributed_key_events_2_rate.gt` | `number` | No | Greater than. | — |
| `metric_filters.attributed_key_events_2_rate.gte` | `number` | No | At least. | — |
| `metric_filters.attributed_key_events_2_rate.lt` | `number` | No | Less than. | — |
| `metric_filters.attributed_key_events_2_rate.lte` | `number` | No | At most. | — |
| `metric_filters.attributed_key_events_2_rate.neq` | `number` | No | Not equal to. | — |
| `metric_filters.attributed_key_events_3` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.attributed_key_events_3.eq` | `number` | No | Equal to. | — |
| `metric_filters.attributed_key_events_3.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.attributed_key_events_3.gt` | `number` | No | Greater than. | — |
| `metric_filters.attributed_key_events_3.gte` | `number` | No | At least. | — |
| `metric_filters.attributed_key_events_3.lt` | `number` | No | Less than. | — |
| `metric_filters.attributed_key_events_3.lte` | `number` | No | At most. | — |
| `metric_filters.attributed_key_events_3.neq` | `number` | No | Not equal to. | — |
| `metric_filters.attributed_key_events_3_rate` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.attributed_key_events_3_rate.eq` | `number` | No | Equal to. | — |
| `metric_filters.attributed_key_events_3_rate.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.attributed_key_events_3_rate.gt` | `number` | No | Greater than. | — |
| `metric_filters.attributed_key_events_3_rate.gte` | `number` | No | At least. | — |
| `metric_filters.attributed_key_events_3_rate.lt` | `number` | No | Less than. | — |
| `metric_filters.attributed_key_events_3_rate.lte` | `number` | No | At most. | — |
| `metric_filters.attributed_key_events_3_rate.neq` | `number` | No | Not equal to. | — |
| `metric_filters.attributed_revenue` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.attributed_revenue.eq` | `number` | No | Equal to. | — |
| `metric_filters.attributed_revenue.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.attributed_revenue.gt` | `number` | No | Greater than. | — |
| `metric_filters.attributed_revenue.gte` | `number` | No | At least. | — |
| `metric_filters.attributed_revenue.lt` | `number` | No | Less than. | — |
| `metric_filters.attributed_revenue.lte` | `number` | No | At most. | — |
| `metric_filters.attributed_revenue.neq` | `number` | No | Not equal to. | — |
| `metric_filters.attributed_transaction_rate` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.attributed_transaction_rate.eq` | `number` | No | Equal to. | — |
| `metric_filters.attributed_transaction_rate.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.attributed_transaction_rate.gt` | `number` | No | Greater than. | — |
| `metric_filters.attributed_transaction_rate.gte` | `number` | No | At least. | — |
| `metric_filters.attributed_transaction_rate.lt` | `number` | No | Less than. | — |
| `metric_filters.attributed_transaction_rate.lte` | `number` | No | At most. | — |
| `metric_filters.attributed_transaction_rate.neq` | `number` | No | Not equal to. | — |
| `metric_filters.attributed_transactions` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.attributed_transactions.eq` | `number` | No | Equal to. | — |
| `metric_filters.attributed_transactions.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.attributed_transactions.gt` | `number` | No | Greater than. | — |
| `metric_filters.attributed_transactions.gte` | `number` | No | At least. | — |
| `metric_filters.attributed_transactions.lt` | `number` | No | Less than. | — |
| `metric_filters.attributed_transactions.lte` | `number` | No | At most. | — |
| `metric_filters.attributed_transactions.neq` | `number` | No | Not equal to. | — |
| `metric_filters.average_click_position` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.average_click_position.eq` | `number` | No | Equal to. | — |
| `metric_filters.average_click_position.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.average_click_position.gt` | `number` | No | Greater than. | — |
| `metric_filters.average_click_position.gte` | `number` | No | At least. | — |
| `metric_filters.average_click_position.lt` | `number` | No | Less than. | — |
| `metric_filters.average_click_position.lte` | `number` | No | At most. | — |
| `metric_filters.average_click_position.neq` | `number` | No | Not equal to. | — |
| `metric_filters.click_through_rate` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.click_through_rate.eq` | `number` | No | Equal to. | — |
| `metric_filters.click_through_rate.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.click_through_rate.gt` | `number` | No | Greater than. | — |
| `metric_filters.click_through_rate.gte` | `number` | No | At least. | — |
| `metric_filters.click_through_rate.lt` | `number` | No | Less than. | — |
| `metric_filters.click_through_rate.lte` | `number` | No | At most. | — |
| `metric_filters.click_through_rate.neq` | `number` | No | Not equal to. | — |
| `metric_filters.clicks` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.clicks.eq` | `number` | No | Equal to. | — |
| `metric_filters.clicks.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.clicks.gt` | `number` | No | Greater than. | — |
| `metric_filters.clicks.gte` | `number` | No | At least. | — |
| `metric_filters.clicks.lt` | `number` | No | Less than. | — |
| `metric_filters.clicks.lte` | `number` | No | At most. | — |
| `metric_filters.clicks.neq` | `number` | No | Not equal to. | — |
| `metric_filters.exit_rate` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.exit_rate.eq` | `number` | No | Equal to. | — |
| `metric_filters.exit_rate.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.exit_rate.gt` | `number` | No | Greater than. | — |
| `metric_filters.exit_rate.gte` | `number` | No | At least. | — |
| `metric_filters.exit_rate.lt` | `number` | No | Less than. | — |
| `metric_filters.exit_rate.lte` | `number` | No | At most. | — |
| `metric_filters.exit_rate.neq` | `number` | No | Not equal to. | — |
| `metric_filters.last_no_results_at` | `object` | No | Operators on one instant; every bound carries an offset and is read as UTC. | — |
| `metric_filters.last_no_results_at.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.last_no_results_at.gt` | `string` | No | Greater than. | format: date-time |
| `metric_filters.last_no_results_at.gte` | `string` | No | At least. | format: date-time |
| `metric_filters.last_no_results_at.lt` | `string` | No | Less than. | format: date-time |
| `metric_filters.last_no_results_at.lte` | `string` | No | At most. | format: date-time |
| `metric_filters.last_unfiltered_no_results_at` | `object` | No | Operators on one instant; every bound carries an offset and is read as UTC. | — |
| `metric_filters.last_unfiltered_no_results_at.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.last_unfiltered_no_results_at.gt` | `string` | No | Greater than. | format: date-time |
| `metric_filters.last_unfiltered_no_results_at.gte` | `string` | No | At least. | format: date-time |
| `metric_filters.last_unfiltered_no_results_at.lt` | `string` | No | Less than. | format: date-time |
| `metric_filters.last_unfiltered_no_results_at.lte` | `string` | No | At most. | format: date-time |
| `metric_filters.no_results_rate` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.no_results_rate.eq` | `number` | No | Equal to. | — |
| `metric_filters.no_results_rate.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.no_results_rate.gt` | `number` | No | Greater than. | — |
| `metric_filters.no_results_rate.gte` | `number` | No | At least. | — |
| `metric_filters.no_results_rate.lt` | `number` | No | Less than. | — |
| `metric_filters.no_results_rate.lte` | `number` | No | At most. | — |
| `metric_filters.no_results_rate.neq` | `number` | No | Not equal to. | — |
| `metric_filters.queries` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.queries.eq` | `number` | No | Equal to. | — |
| `metric_filters.queries.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.queries.gt` | `number` | No | Greater than. | — |
| `metric_filters.queries.gte` | `number` | No | At least. | — |
| `metric_filters.queries.lt` | `number` | No | Less than. | — |
| `metric_filters.queries.lte` | `number` | No | At most. | — |
| `metric_filters.queries.neq` | `number` | No | Not equal to. | — |
| `metric_filters.queries_without_results` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.queries_without_results.eq` | `number` | No | Equal to. | — |
| `metric_filters.queries_without_results.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.queries_without_results.gt` | `number` | No | Greater than. | — |
| `metric_filters.queries_without_results.gte` | `number` | No | At least. | — |
| `metric_filters.queries_without_results.lt` | `number` | No | Less than. | — |
| `metric_filters.queries_without_results.lte` | `number` | No | At most. | — |
| `metric_filters.queries_without_results.neq` | `number` | No | Not equal to. | — |
| `metric_filters.reformulation_rate` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.reformulation_rate.eq` | `number` | No | Equal to. | — |
| `metric_filters.reformulation_rate.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.reformulation_rate.gt` | `number` | No | Greater than. | — |
| `metric_filters.reformulation_rate.gte` | `number` | No | At least. | — |
| `metric_filters.reformulation_rate.lt` | `number` | No | Less than. | — |
| `metric_filters.reformulation_rate.lte` | `number` | No | At most. | — |
| `metric_filters.reformulation_rate.neq` | `number` | No | Not equal to. | — |
| `metric_filters.searches` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.searches.eq` | `number` | No | Equal to. | — |
| `metric_filters.searches.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.searches.gt` | `number` | No | Greater than. | — |
| `metric_filters.searches.gte` | `number` | No | At least. | — |
| `metric_filters.searches.lt` | `number` | No | Less than. | — |
| `metric_filters.searches.lte` | `number` | No | At most. | — |
| `metric_filters.searches.neq` | `number` | No | Not equal to. | — |
| `metric_filters.searches_without_clicks` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.searches_without_clicks.eq` | `number` | No | Equal to. | — |
| `metric_filters.searches_without_clicks.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.searches_without_clicks.gt` | `number` | No | Greater than. | — |
| `metric_filters.searches_without_clicks.gte` | `number` | No | At least. | — |
| `metric_filters.searches_without_clicks.lt` | `number` | No | Less than. | — |
| `metric_filters.searches_without_clicks.lte` | `number` | No | At most. | — |
| `metric_filters.searches_without_clicks.neq` | `number` | No | Not equal to. | — |
| `metric_filters.searches_without_results` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.searches_without_results.eq` | `number` | No | Equal to. | — |
| `metric_filters.searches_without_results.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.searches_without_results.gt` | `number` | No | Greater than. | — |
| `metric_filters.searches_without_results.gte` | `number` | No | At least. | — |
| `metric_filters.searches_without_results.lt` | `number` | No | Less than. | — |
| `metric_filters.searches_without_results.lte` | `number` | No | At most. | — |
| `metric_filters.searches_without_results.neq` | `number` | No | Not equal to. | — |
| `metric_filters.sessions` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.sessions.eq` | `number` | No | Equal to. | — |
| `metric_filters.sessions.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.sessions.gt` | `number` | No | Greater than. | — |
| `metric_filters.sessions.gte` | `number` | No | At least. | — |
| `metric_filters.sessions.lt` | `number` | No | Less than. | — |
| `metric_filters.sessions.lte` | `number` | No | At most. | — |
| `metric_filters.sessions.neq` | `number` | No | Not equal to. | — |
| `metric_filters.sessions_attributed_key_events_1_rate` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.sessions_attributed_key_events_1_rate.eq` | `number` | No | Equal to. | — |
| `metric_filters.sessions_attributed_key_events_1_rate.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.sessions_attributed_key_events_1_rate.gt` | `number` | No | Greater than. | — |
| `metric_filters.sessions_attributed_key_events_1_rate.gte` | `number` | No | At least. | — |
| `metric_filters.sessions_attributed_key_events_1_rate.lt` | `number` | No | Less than. | — |
| `metric_filters.sessions_attributed_key_events_1_rate.lte` | `number` | No | At most. | — |
| `metric_filters.sessions_attributed_key_events_1_rate.neq` | `number` | No | Not equal to. | — |
| `metric_filters.sessions_attributed_key_events_2_rate` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.sessions_attributed_key_events_2_rate.eq` | `number` | No | Equal to. | — |
| `metric_filters.sessions_attributed_key_events_2_rate.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.sessions_attributed_key_events_2_rate.gt` | `number` | No | Greater than. | — |
| `metric_filters.sessions_attributed_key_events_2_rate.gte` | `number` | No | At least. | — |
| `metric_filters.sessions_attributed_key_events_2_rate.lt` | `number` | No | Less than. | — |
| `metric_filters.sessions_attributed_key_events_2_rate.lte` | `number` | No | At most. | — |
| `metric_filters.sessions_attributed_key_events_2_rate.neq` | `number` | No | Not equal to. | — |
| `metric_filters.sessions_attributed_key_events_3_rate` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.sessions_attributed_key_events_3_rate.eq` | `number` | No | Equal to. | — |
| `metric_filters.sessions_attributed_key_events_3_rate.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.sessions_attributed_key_events_3_rate.gt` | `number` | No | Greater than. | — |
| `metric_filters.sessions_attributed_key_events_3_rate.gte` | `number` | No | At least. | — |
| `metric_filters.sessions_attributed_key_events_3_rate.lt` | `number` | No | Less than. | — |
| `metric_filters.sessions_attributed_key_events_3_rate.lte` | `number` | No | At most. | — |
| `metric_filters.sessions_attributed_key_events_3_rate.neq` | `number` | No | Not equal to. | — |
| `metric_filters.sessions_attributed_transaction_rate` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.sessions_attributed_transaction_rate.eq` | `number` | No | Equal to. | — |
| `metric_filters.sessions_attributed_transaction_rate.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.sessions_attributed_transaction_rate.gt` | `number` | No | Greater than. | — |
| `metric_filters.sessions_attributed_transaction_rate.gte` | `number` | No | At least. | — |
| `metric_filters.sessions_attributed_transaction_rate.lt` | `number` | No | Less than. | — |
| `metric_filters.sessions_attributed_transaction_rate.lte` | `number` | No | At most. | — |
| `metric_filters.sessions_attributed_transaction_rate.neq` | `number` | No | Not equal to. | — |
| `metric_filters.sessions_click_through_rate` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.sessions_click_through_rate.eq` | `number` | No | Equal to. | — |
| `metric_filters.sessions_click_through_rate.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.sessions_click_through_rate.gt` | `number` | No | Greater than. | — |
| `metric_filters.sessions_click_through_rate.gte` | `number` | No | At least. | — |
| `metric_filters.sessions_click_through_rate.lt` | `number` | No | Less than. | — |
| `metric_filters.sessions_click_through_rate.lte` | `number` | No | At most. | — |
| `metric_filters.sessions_click_through_rate.neq` | `number` | No | Not equal to. | — |
| `metric_filters.sessions_no_results_rate` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.sessions_no_results_rate.eq` | `number` | No | Equal to. | — |
| `metric_filters.sessions_no_results_rate.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.sessions_no_results_rate.gt` | `number` | No | Greater than. | — |
| `metric_filters.sessions_no_results_rate.gte` | `number` | No | At least. | — |
| `metric_filters.sessions_no_results_rate.lt` | `number` | No | Less than. | — |
| `metric_filters.sessions_no_results_rate.lte` | `number` | No | At most. | — |
| `metric_filters.sessions_no_results_rate.neq` | `number` | No | Not equal to. | — |
| `metric_filters.unfiltered_no_results_rate` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.unfiltered_no_results_rate.eq` | `number` | No | Equal to. | — |
| `metric_filters.unfiltered_no_results_rate.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.unfiltered_no_results_rate.gt` | `number` | No | Greater than. | — |
| `metric_filters.unfiltered_no_results_rate.gte` | `number` | No | At least. | — |
| `metric_filters.unfiltered_no_results_rate.lt` | `number` | No | Less than. | — |
| `metric_filters.unfiltered_no_results_rate.lte` | `number` | No | At most. | — |
| `metric_filters.unfiltered_no_results_rate.neq` | `number` | No | Not equal to. | — |
| `metric_filters.unfiltered_searches_without_results` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.unfiltered_searches_without_results.eq` | `number` | No | Equal to. | — |
| `metric_filters.unfiltered_searches_without_results.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.unfiltered_searches_without_results.gt` | `number` | No | Greater than. | — |
| `metric_filters.unfiltered_searches_without_results.gte` | `number` | No | At least. | — |
| `metric_filters.unfiltered_searches_without_results.lt` | `number` | No | Less than. | — |
| `metric_filters.unfiltered_searches_without_results.lte` | `number` | No | At most. | — |
| `metric_filters.unfiltered_searches_without_results.neq` | `number` | No | Not equal to. | — |
| `metric_filters.unfiltered_users_without_results` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.unfiltered_users_without_results.eq` | `number` | No | Equal to. | — |
| `metric_filters.unfiltered_users_without_results.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.unfiltered_users_without_results.gt` | `number` | No | Greater than. | — |
| `metric_filters.unfiltered_users_without_results.gte` | `number` | No | At least. | — |
| `metric_filters.unfiltered_users_without_results.lt` | `number` | No | Less than. | — |
| `metric_filters.unfiltered_users_without_results.lte` | `number` | No | At most. | — |
| `metric_filters.unfiltered_users_without_results.neq` | `number` | No | Not equal to. | — |
| `metric_filters.users` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.users.eq` | `number` | No | Equal to. | — |
| `metric_filters.users.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.users.gt` | `number` | No | Greater than. | — |
| `metric_filters.users.gte` | `number` | No | At least. | — |
| `metric_filters.users.lt` | `number` | No | Less than. | — |
| `metric_filters.users.lte` | `number` | No | At most. | — |
| `metric_filters.users.neq` | `number` | No | Not equal to. | — |
| `metric_filters.users_attributed_key_events_1_rate` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.users_attributed_key_events_1_rate.eq` | `number` | No | Equal to. | — |
| `metric_filters.users_attributed_key_events_1_rate.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.users_attributed_key_events_1_rate.gt` | `number` | No | Greater than. | — |
| `metric_filters.users_attributed_key_events_1_rate.gte` | `number` | No | At least. | — |
| `metric_filters.users_attributed_key_events_1_rate.lt` | `number` | No | Less than. | — |
| `metric_filters.users_attributed_key_events_1_rate.lte` | `number` | No | At most. | — |
| `metric_filters.users_attributed_key_events_1_rate.neq` | `number` | No | Not equal to. | — |
| `metric_filters.users_attributed_key_events_2_rate` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.users_attributed_key_events_2_rate.eq` | `number` | No | Equal to. | — |
| `metric_filters.users_attributed_key_events_2_rate.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.users_attributed_key_events_2_rate.gt` | `number` | No | Greater than. | — |
| `metric_filters.users_attributed_key_events_2_rate.gte` | `number` | No | At least. | — |
| `metric_filters.users_attributed_key_events_2_rate.lt` | `number` | No | Less than. | — |
| `metric_filters.users_attributed_key_events_2_rate.lte` | `number` | No | At most. | — |
| `metric_filters.users_attributed_key_events_2_rate.neq` | `number` | No | Not equal to. | — |
| `metric_filters.users_attributed_key_events_3_rate` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.users_attributed_key_events_3_rate.eq` | `number` | No | Equal to. | — |
| `metric_filters.users_attributed_key_events_3_rate.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.users_attributed_key_events_3_rate.gt` | `number` | No | Greater than. | — |
| `metric_filters.users_attributed_key_events_3_rate.gte` | `number` | No | At least. | — |
| `metric_filters.users_attributed_key_events_3_rate.lt` | `number` | No | Less than. | — |
| `metric_filters.users_attributed_key_events_3_rate.lte` | `number` | No | At most. | — |
| `metric_filters.users_attributed_key_events_3_rate.neq` | `number` | No | Not equal to. | — |
| `metric_filters.users_attributed_transaction_rate` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.users_attributed_transaction_rate.eq` | `number` | No | Equal to. | — |
| `metric_filters.users_attributed_transaction_rate.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.users_attributed_transaction_rate.gt` | `number` | No | Greater than. | — |
| `metric_filters.users_attributed_transaction_rate.gte` | `number` | No | At least. | — |
| `metric_filters.users_attributed_transaction_rate.lt` | `number` | No | Less than. | — |
| `metric_filters.users_attributed_transaction_rate.lte` | `number` | No | At most. | — |
| `metric_filters.users_attributed_transaction_rate.neq` | `number` | No | Not equal to. | — |
| `metric_filters.users_click_through_rate` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.users_click_through_rate.eq` | `number` | No | Equal to. | — |
| `metric_filters.users_click_through_rate.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.users_click_through_rate.gt` | `number` | No | Greater than. | — |
| `metric_filters.users_click_through_rate.gte` | `number` | No | At least. | — |
| `metric_filters.users_click_through_rate.lt` | `number` | No | Less than. | — |
| `metric_filters.users_click_through_rate.lte` | `number` | No | At most. | — |
| `metric_filters.users_click_through_rate.neq` | `number` | No | Not equal to. | — |
| `metric_filters.users_no_results_rate` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.users_no_results_rate.eq` | `number` | No | Equal to. | — |
| `metric_filters.users_no_results_rate.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.users_no_results_rate.gt` | `number` | No | Greater than. | — |
| `metric_filters.users_no_results_rate.gte` | `number` | No | At least. | — |
| `metric_filters.users_no_results_rate.lt` | `number` | No | Less than. | — |
| `metric_filters.users_no_results_rate.lte` | `number` | No | At most. | — |
| `metric_filters.users_no_results_rate.neq` | `number` | No | Not equal to. | — |
| `metric_filters.users_without_results` | `object` | No | Operators on one numeric field. | — |
| `metric_filters.users_without_results.eq` | `number` | No | Equal to. | — |
| `metric_filters.users_without_results.exists` | `boolean` | No | Has a value (`true`) or has none (`false`). | — |
| `metric_filters.users_without_results.gt` | `number` | No | Greater than. | — |
| `metric_filters.users_without_results.gte` | `number` | No | At least. | — |
| `metric_filters.users_without_results.lt` | `number` | No | Less than. | — |
| `metric_filters.users_without_results.lte` | `number` | No | At most. | — |
| `metric_filters.users_without_results.neq` | `number` | No | Not equal to. | — |
| `metrics` | `Array<string>` | No | Metrics to compute; when left out, every metric except `queries` and `queries_without_results`, which are 1 or 0 on a query row. | >= 1 items |
| `sort` | `object` | No | Order of `items`. | — |
| `sort.direction` | `string` | Yes | `asc` for ascending order, `desc` for descending. | allowed values: asc, desc |
| `sort.field` | `string` | Yes | Metric to order by; one not in `metrics` is added to the response. | allowed values: users, sessions, searches, queries, clicks, click_through_rate, users_click_through_rate, sessions_click_through_rate, searches_without_clicks, attributed_cart_value, attributed_transactions, attributed_transaction_rate, users_attributed_transaction_rate, sessions_attributed_transaction_rate, attributed_revenue, attributed_average_order_value, attributed_key_events_1, attributed_key_events_1_rate, users_attributed_key_events_1_rate, sessions_attributed_key_events_1_rate, attributed_key_events_2, attributed_key_events_2_rate, users_attributed_key_events_2_rate, sessions_attributed_key_events_2_rate, attributed_key_events_3, attributed_key_events_3_rate, users_attributed_key_events_3_rate, sessions_attributed_key_events_3_rate, searches_without_results, no_results_rate, users_no_results_rate, sessions_no_results_rate, users_without_results, queries_without_results, last_no_results_at, unfiltered_searches_without_results, unfiltered_no_results_rate, unfiltered_users_without_results, last_unfiltered_no_results_at, exit_rate, reformulation_rate, average_click_position |
| `touchpoints` | `Array<string>` | Yes | Where the lists were shown. As with `channel_ids`, the touchpoints are pooled: one total, one series line and one row per key across all of them, and `group_by: ["touchpoint"]` splits them. Pooled, the counts of searches, impressions, clicks, transactions and key events add up, and so does money; users, sessions and queries count once however many of the touchpoints they appear at; and a rate is taken over the pooled lists. `searches` counts the lists shown, so an autocomplete submitted as a search counts once at each touchpoint, and an average position mixes the two touchpoints' scales. A reformulation is a change of query on the next list at the same touchpoint. | >= 1 items |

#### Request body example

```json
{
  "attribution_model": "last_touch",
  "date_range": {
    "date_from": "2026-04-15T12:00:00Z",
    "date_to": "2026-04-15T12:00:00Z"
  },
  "filters": {
    "$and": [
      {}
    ],
    "$not": {},
    "$or": [
      {}
    ]
  },
  "group_by": [],
  "metric_filters": {
    "$and": [
      {}
    ],
    "$not": {},
    "$or": [
      {}
    ]
  },
  "metrics": [
    "users"
  ],
  "sort": {
    "direction": "desc",
    "field": "searches"
  },
  "touchpoints": [
    "autocomplete"
  ]
}
```

## Responses

| Status | Description | Content |
|---|---|---|
| `200` | Successful Response | application/json: object |
| `400` | Malformed request | application/json: object |
| `401` | Missing or invalid credentials | application/json: object |
| `403` | Authenticated but not permitted | application/json: object |
| `422` | Request validation failed, or the report cannot answer it as asked (`exception_details.problems`). | application/json: object |
| `503` | Service temporarily unavailable | application/json: object |

### 200

Successful Response

#### application/json

Schema: `object`

##### Attributes

| Attribute | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `items` | `Array<object>` | Yes | The items on this page. | — |
| `items[].group` | `object` | No | Its `group_by` values; present with `group_by`. | — |
| `items[].group.channel_id` | `anyOf(string, null)` | No | The channel the counts come from. | — |
| `items[].group.consent_granted` | `anyOf(boolean, null)` | No | The visitor granted personalization consent. | — |
| `items[].group.context` | `anyOf(object, null)` | No | Context values grouped as `context.<name>`, keyed by name. | — |
| `items[].group.context.*` | `anyOf(string, null)` | No | Additional property. | — |
| `items[].group.device` | `anyOf(string, null)` | No | Device: `desktop`, `mobile`, `tablet`, … | — |
| `items[].group.external_ab_test_variant` | `anyOf(string, null)` | No | Variant of the client's own A/B test. | — |
| `items[].group.internal_ab_test_id` | `anyOf(string, null)` | No | Luigi's Box A/B test. | — |
| `items[].group.internal_ab_test_variant` | `anyOf(string, null)` | No | Variant of the Luigi's Box A/B test. | — |
| `items[].group.landing_page` | `anyOf(string, null)` | No | The entry URL. | — |
| `items[].group.landing_page_host` | `anyOf(string, null)` | No | The entry URL's host. | — |
| `items[].group.personalized` | `anyOf(boolean, null)` | No | The session was served personalized results. | — |
| `items[].group.platform` | `anyOf(string, null)` | No | Platform: `ios`, `android`, `windows`, … | — |
| `items[].group.result_type` | `anyOf(string, null)` | No | Type of the result: `item`, `category`, `brand`, … | — |
| `items[].group.returning` | `anyOf(boolean, null)` | No | The visitor had an earlier session: `session_rank` of 2 or more. | — |
| `items[].group.surface_id` | `anyOf(string, null)` | No | The Surface that answered. | — |
| `items[].group.touchpoint` | `anyOf(string, null)` | No | Where the lists were shown. | — |
| `items[].group.traffic_source` | `anyOf(string, null)` | No | How the session arrived. | — |
| `items[].group.traffic_source_type` | `anyOf(string, null)` | No | Traffic source type, e.g. `chatgpt`. | — |
| `items[].group.url_host` | `anyOf(string, null)` | No | Host of the page the search ran on, e.g. a language site. | — |
| `items[].group.url_params` | `anyOf(object, null)` | No | URL parameters grouped as `url_params.<name>`, keyed by name, so `url_params.utm_source` reads as `group.url_params.utm_source`. | — |
| `items[].group.url_params.*` | `anyOf(string, null)` | No | Additional property. | — |
| `items[].group.url_path` | `anyOf(string, null)` | No | Path of the page the search ran on, without its query string. | — |
| `items[].metrics` | `object` | Yes | Metrics over `date_range`. | — |
| `items[].metrics.attributed_average_order_value` | `anyOf(number, null)` | No | `attributed_revenue` / `attributed_transactions`; `null` without attributed transactions. | — |
| `items[].metrics.attributed_cart_value` | `anyOf(number, null)` | No | Value of the credited cart additions. | — |
| `items[].metrics.attributed_key_events_1` | `anyOf(number, null)` | No | Key event 1 interactions credited; by default key event 1 counts add-to-carts. | — |
| `items[].metrics.attributed_key_events_1_rate` | `anyOf(number, null)` | No | Searches that led to key event 1 (by default, an add-to-cart) / searches. | — |
| `items[].metrics.attributed_key_events_2` | `anyOf(number, null)` | No | Key event 2 interactions credited. | — |
| `items[].metrics.attributed_key_events_2_rate` | `anyOf(number, null)` | No | Searches that led to key event 2 / searches. | — |
| `items[].metrics.attributed_key_events_3` | `anyOf(number, null)` | No | Key event 3 interactions credited. | — |
| `items[].metrics.attributed_key_events_3_rate` | `anyOf(number, null)` | No | Searches that led to key event 3 / searches. | — |
| `items[].metrics.attributed_revenue` | `anyOf(number, null)` | No | Order value of the credited transactions. | — |
| `items[].metrics.attributed_transaction_rate` | `anyOf(number, null)` | No | Searches with an attributed transaction / searches. | — |
| `items[].metrics.attributed_transactions` | `anyOf(number, null)` | No | Transactions credited to search results. | — |
| `items[].metrics.average_click_position` | `anyOf(number, null)` | No | Average position of clicked results; `null` without clicks. | — |
| `items[].metrics.click_through_rate` | `anyOf(number, null)` | No | Searches with a click / searches. | — |
| `items[].metrics.clicks` | `anyOf(number, null)` | No | Clicks on results. | — |
| `items[].metrics.exit_rate` | `anyOf(number, null)` | No | Sessions that ended on the search / sessions. | — |
| `items[].metrics.last_no_results_at` | `anyOf(string, null)` | No | Latest search without results. | — |
| `items[].metrics.last_unfiltered_no_results_at` | `anyOf(string, null)` | No | Latest unfiltered search without results. A filter whose name starts with `_` is the client's own bookkeeping and never counts. | — |
| `items[].metrics.no_results_rate` | `anyOf(number, null)` | No | Searches without results / searches. | — |
| `items[].metrics.queries` | `anyOf(integer, null)` | No | Distinct queries. | — |
| `items[].metrics.queries_without_results` | `anyOf(integer, null)` | No | Distinct queries that returned nothing at least once. | — |
| `items[].metrics.reformulation_rate` | `anyOf(number, null)` | No | Users who changed the query on their next search at the same touchpoint / users. | — |
| `items[].metrics.searches` | `anyOf(integer, null)` | No | Searches. | — |
| `items[].metrics.searches_without_clicks` | `anyOf(integer, null)` | No | Searches with no click. | — |
| `items[].metrics.searches_without_results` | `anyOf(integer, null)` | No | Searches that returned nothing and were not redirected. | — |
| `items[].metrics.sessions` | `anyOf(integer, null)` | No | Sessions with a search. | — |
| `items[].metrics.sessions_attributed_key_events_1_rate` | `anyOf(number, null)` | No | Sessions that reached key event 1 (by default, an add-to-cart) / sessions. | — |
| `items[].metrics.sessions_attributed_key_events_2_rate` | `anyOf(number, null)` | No | Sessions that reached key event 2 / sessions. | — |
| `items[].metrics.sessions_attributed_key_events_3_rate` | `anyOf(number, null)` | No | Sessions that reached key event 3 / sessions. | — |
| `items[].metrics.sessions_attributed_transaction_rate` | `anyOf(number, null)` | No | Sessions with an attributed transaction / sessions. | — |
| `items[].metrics.sessions_click_through_rate` | `anyOf(number, null)` | No | Sessions with a click / sessions. | — |
| `items[].metrics.sessions_no_results_rate` | `anyOf(number, null)` | No | Sessions with a search without results / sessions. | — |
| `items[].metrics.unfiltered_no_results_rate` | `anyOf(number, null)` | No | Unfiltered searches without results / all searches. A filter whose name starts with `_` is the client's own bookkeeping and never counts. | — |
| `items[].metrics.unfiltered_searches_without_results` | `anyOf(integer, null)` | No | Searches without results that applied no filter. A filter whose name starts with `_` is the client's own bookkeeping and never counts. | — |
| `items[].metrics.unfiltered_users_without_results` | `anyOf(integer, null)` | No | Users who got an unfiltered search without results. A filter whose name starts with `_` is the client's own bookkeeping and never counts. | — |
| `items[].metrics.users` | `anyOf(integer, null)` | No | Unique users who searched. | — |
| `items[].metrics.users_attributed_key_events_1_rate` | `anyOf(number, null)` | No | Users who reached key event 1 (by default, an add-to-cart) / users. | — |
| `items[].metrics.users_attributed_key_events_2_rate` | `anyOf(number, null)` | No | Users who reached key event 2 / users. | — |
| `items[].metrics.users_attributed_key_events_3_rate` | `anyOf(number, null)` | No | Users who reached key event 3 / users. | — |
| `items[].metrics.users_attributed_transaction_rate` | `anyOf(number, null)` | No | Users with an attributed transaction / users. | — |
| `items[].metrics.users_click_through_rate` | `anyOf(number, null)` | No | Users who clicked / users. | — |
| `items[].metrics.users_no_results_rate` | `anyOf(number, null)` | No | Users who got no results / users. | — |
| `items[].metrics.users_without_results` | `anyOf(integer, null)` | No | Users who got no results. | — |
| `items[].query` | `string` | Yes | The query, lowercased and trimmed. | — |
| `page` | `integer` | Yes | 1-based page number. | — |
| `size` | `integer` | Yes | Number of items per page. | — |
| `total` | `integer` | Yes | Total number of items across all pages. | — |

##### Response example

```json
{
  "items": [
    {
      "group": {
        "channel_id": "example",
        "consent_granted": true,
        "context": {
          "additionalProperty": "example"
        },
        "device": "example",
        "external_ab_test_variant": "example",
        "internal_ab_test_id": "example",
        "internal_ab_test_variant": "example",
        "landing_page": "example",
        "landing_page_host": "example",
        "personalized": true,
        "platform": "example",
        "result_type": "example",
        "returning": true,
        "surface_id": "example",
        "touchpoint": "autocomplete",
        "traffic_source": "direct",
        "traffic_source_type": "example",
        "url_host": "example",
        "url_params": {
          "additionalProperty": "example"
        },
        "url_path": "example"
      },
      "metrics": {
        "attributed_average_order_value": 1,
        "attributed_cart_value": 1,
        "attributed_key_events_1": 1,
        "attributed_key_events_1_rate": 1,
        "attributed_key_events_2": 1,
        "attributed_key_events_2_rate": 1,
        "attributed_key_events_3": 1,
        "attributed_key_events_3_rate": 1,
        "attributed_revenue": 1,
        "attributed_transaction_rate": 1,
        "attributed_transactions": 1,
        "average_click_position": 1,
        "click_through_rate": 1,
        "clicks": 1,
        "exit_rate": 1,
        "last_no_results_at": "2026-04-15T12:00:00Z",
        "last_unfiltered_no_results_at": "2026-04-15T12:00:00Z",
        "no_results_rate": 1,
        "queries": 1,
        "queries_without_results": 1,
        "reformulation_rate": 1,
        "searches": 1,
        "searches_without_clicks": 1,
        "searches_without_results": 1,
        "sessions": 1,
        "sessions_attributed_key_events_1_rate": 1,
        "sessions_attributed_key_events_2_rate": 1,
        "sessions_attributed_key_events_3_rate": 1,
        "sessions_attributed_transaction_rate": 1,
        "sessions_click_through_rate": 1,
        "sessions_no_results_rate": 1,
        "unfiltered_no_results_rate": 1,
        "unfiltered_searches_without_results": 1,
        "unfiltered_users_without_results": 1,
        "users": 1,
        "users_attributed_key_events_1_rate": 1,
        "users_attributed_key_events_2_rate": 1,
        "users_attributed_key_events_3_rate": 1,
        "users_attributed_transaction_rate": 1,
        "users_click_through_rate": 1,
        "users_no_results_rate": 1,
        "users_without_results": 1
      },
      "query": "example"
    }
  ],
  "page": 1,
  "size": 1,
  "total": 1
}
```

### 400

Malformed request

#### application/json

Schema: `object`

##### Attributes

| Attribute | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `exception_details` | `object` | No | Machine-readable error context; empty object when there is nothing to add. | — |
| `exception_details.error_code` | `string` | No | Stable machine code naming why a well-formed request was refused: snake_case, prefixed by its domain — e.g. `filter_unknown_field` or `cursor_mismatch`. Safe to branch on; `reason` is not. Absent when the status code says all there is to say. | — |
| `exception_details.validation_errors` | `Array<object>` | No | Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value. | — |
| `exception_details.validation_errors[].loc` | `Array<anyOf(string, integer)>` | Yes | Path to the offending value from the request root, e.g. `["body", "filters", 0, "operator"]`. | — |
| `exception_details.validation_errors[].msg` | `string` | Yes | What is wrong with the value at `loc`. | — |
| `exception_details.validation_errors[].type` | `string` | Yes | Stable machine code for the problem, e.g. `missing` or `string_too_short`. | — |
| `exception_details.*` | `any` | No | Additional property. | — |
| `reason` | `string` | Yes | Human-readable, actionable error message. | — |
| `request_id` | `anyOf(string, null)` | No | Request correlation ID (matches the X-Request-Id response header). | — |

##### Response example

```json
{
  "exception_details": {
    "error_code": "example",
    "validation_errors": [
      {
        "loc": [
          "example"
        ],
        "msg": "example",
        "type": "example"
      }
    ]
  },
  "reason": "example",
  "request_id": "example"
}
```

### 401

Missing or invalid credentials

#### application/json

Schema: `object`

##### Attributes

| Attribute | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `exception_details` | `object` | No | Machine-readable error context; empty object when there is nothing to add. | — |
| `exception_details.error_code` | `string` | No | Stable machine code naming why a well-formed request was refused: snake_case, prefixed by its domain — e.g. `filter_unknown_field` or `cursor_mismatch`. Safe to branch on; `reason` is not. Absent when the status code says all there is to say. | — |
| `exception_details.validation_errors` | `Array<object>` | No | Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value. | — |
| `exception_details.validation_errors[].loc` | `Array<anyOf(string, integer)>` | Yes | Path to the offending value from the request root, e.g. `["body", "filters", 0, "operator"]`. | — |
| `exception_details.validation_errors[].msg` | `string` | Yes | What is wrong with the value at `loc`. | — |
| `exception_details.validation_errors[].type` | `string` | Yes | Stable machine code for the problem, e.g. `missing` or `string_too_short`. | — |
| `exception_details.*` | `any` | No | Additional property. | — |
| `reason` | `string` | Yes | Human-readable, actionable error message. | — |
| `request_id` | `anyOf(string, null)` | No | Request correlation ID (matches the X-Request-Id response header). | — |

##### Response example

```json
{
  "exception_details": {
    "error_code": "example",
    "validation_errors": [
      {
        "loc": [
          "example"
        ],
        "msg": "example",
        "type": "example"
      }
    ]
  },
  "reason": "example",
  "request_id": "example"
}
```

### 403

Authenticated but not permitted

#### application/json

Schema: `object`

##### Attributes

| Attribute | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `exception_details` | `object` | No | Machine-readable error context; empty object when there is nothing to add. | — |
| `exception_details.error_code` | `string` | No | Stable machine code naming why a well-formed request was refused: snake_case, prefixed by its domain — e.g. `filter_unknown_field` or `cursor_mismatch`. Safe to branch on; `reason` is not. Absent when the status code says all there is to say. | — |
| `exception_details.validation_errors` | `Array<object>` | No | Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value. | — |
| `exception_details.validation_errors[].loc` | `Array<anyOf(string, integer)>` | Yes | Path to the offending value from the request root, e.g. `["body", "filters", 0, "operator"]`. | — |
| `exception_details.validation_errors[].msg` | `string` | Yes | What is wrong with the value at `loc`. | — |
| `exception_details.validation_errors[].type` | `string` | Yes | Stable machine code for the problem, e.g. `missing` or `string_too_short`. | — |
| `exception_details.*` | `any` | No | Additional property. | — |
| `reason` | `string` | Yes | Human-readable, actionable error message. | — |
| `request_id` | `anyOf(string, null)` | No | Request correlation ID (matches the X-Request-Id response header). | — |

##### Response example

```json
{
  "exception_details": {
    "error_code": "example",
    "validation_errors": [
      {
        "loc": [
          "example"
        ],
        "msg": "example",
        "type": "example"
      }
    ]
  },
  "reason": "example",
  "request_id": "example"
}
```

### 422

Request validation failed, or the report cannot answer it as asked (`exception_details.problems`).

#### application/json

Schema: `object`

##### Attributes

| Attribute | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `exception_details` | `object` | Yes | Machine-readable error context. | — |
| `exception_details.error_code` | `string` | No | Stable machine code naming why a well-formed request was refused: snake_case, prefixed by its domain — e.g. `filter_unknown_field` or `cursor_mismatch`. Safe to branch on; `reason` is not. Absent when the status code says all there is to say. | — |
| `exception_details.problems` | `Array<object>` | No | Why the report cannot answer the request as asked; `validation_errors` covers malformed fields. | — |
| `exception_details.problems[].code` | `string` | Yes | Stable code of the problem; switch on it, not on `message`. | allowed values: too_many_groups, too_many_high_cardinality_groups, too_many_points, ab_test_variant_without_test, nothing_to_compare, report_too_large |
| `exception_details.problems[].loc` | `Array<anyOf(string, integer)>` | Yes | Where in the request, as in `validation_errors[].loc`, e.g. `["body", "group_by", 1]`. | — |
| `exception_details.problems[].message` | `string` | Yes | What to change. | — |
| `exception_details.validation_errors` | `Array<object>` | No | Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value. | — |
| `exception_details.validation_errors[].loc` | `Array<anyOf(string, integer)>` | Yes | Path to the offending value from the request root, e.g. `["body", "filters", 0, "operator"]`. | — |
| `exception_details.validation_errors[].msg` | `string` | Yes | What is wrong with the value at `loc`. | — |
| `exception_details.validation_errors[].type` | `string` | Yes | Stable machine code for the problem, e.g. `missing` or `string_too_short`. | — |
| `exception_details.*` | `any` | No | Additional property. | — |
| `reason` | `string` | Yes | Human-readable, actionable error message. | — |
| `request_id` | `anyOf(string, null)` | No | Request correlation ID (matches the X-Request-Id response header). | — |

##### Response example

```json
{
  "exception_details": {
    "error_code": "example",
    "problems": [
      {
        "code": "too_many_groups",
        "loc": [
          "example"
        ],
        "message": "example"
      }
    ],
    "validation_errors": [
      {
        "loc": [
          "example"
        ],
        "msg": "example",
        "type": "example"
      }
    ]
  },
  "reason": "example",
  "request_id": "example"
}
```

### 503

Service temporarily unavailable

#### application/json

Schema: `object`

##### Attributes

| Attribute | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `exception_details` | `object` | No | Machine-readable error context; empty object when there is nothing to add. | — |
| `exception_details.error_code` | `string` | No | Stable machine code naming why a well-formed request was refused: snake_case, prefixed by its domain — e.g. `filter_unknown_field` or `cursor_mismatch`. Safe to branch on; `reason` is not. Absent when the status code says all there is to say. | — |
| `exception_details.validation_errors` | `Array<object>` | No | Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value. | — |
| `exception_details.validation_errors[].loc` | `Array<anyOf(string, integer)>` | Yes | Path to the offending value from the request root, e.g. `["body", "filters", 0, "operator"]`. | — |
| `exception_details.validation_errors[].msg` | `string` | Yes | What is wrong with the value at `loc`. | — |
| `exception_details.validation_errors[].type` | `string` | Yes | Stable machine code for the problem, e.g. `missing` or `string_too_short`. | — |
| `exception_details.*` | `any` | No | Additional property. | — |
| `reason` | `string` | Yes | Human-readable, actionable error message. | — |
| `request_id` | `anyOf(string, null)` | No | Request correlation ID (matches the X-Request-Id response header). | — |

##### Response example

```json
{
  "exception_details": {
    "error_code": "example",
    "validation_errors": [
      {
        "loc": [
          "example"
        ],
        "msg": "example",
        "type": "example"
      }
    ]
  },
  "reason": "example",
  "request_id": "example"
}
```