# Single searches, newest first

`POST /analytics/v1/searches/events`

Each list as it was shown, for example the latest searches without results.

## Request example

```bash
curl --request POST \
  --url 'https://api.eu1.luigisbox.ai/analytics/v1/searches/events?channel_ids=<channel_ids>&page=1&size=20' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "date_range": {
    "date_from": "2026-04-15T12:00:00Z",
    "date_to": "2026-04-15T12:00:00Z"
  },
  "filters": {
    "$and": [
      {}
    ],
    "$not": {},
    "$or": [
      {}
    ]
  },
  "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 |
|---|---|---|---|---|
| `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 lists are listed; every list 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.no_results` | `object` | No | Operators on one true-or-false field. | — |
| `filters.no_results.eq` | `boolean` | No | Equal to. | — |
| `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 |
| `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
{
  "date_range": {
    "date_from": "2026-04-15T12:00:00Z",
    "date_to": "2026-04-15T12:00:00Z"
  },
  "filters": {
    "$and": [
      {}
    ],
    "$not": {},
    "$or": [
      {}
    ]
  },
  "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[].applied_filters` | `Array<object>` | Yes | The filter values the search applied, one item per value; private filters are left out. A filter whose name starts with `_` is the client's own bookkeeping and never counts. | — |
| `items[].applied_filters[].name` | `string` | Yes | Filter name, e.g. `color`. | — |
| `items[].applied_filters[].value` | `string` | Yes | Value applied, e.g. `red`. | — |
| `items[].channel_id` | `string` | Yes | The channel the search ran in, as a request may cover several. | — |
| `items[].device` | `anyOf(string, null)` | Yes | Device: `desktop`, `mobile`, `tablet`, …; `null` when unknown. | — |
| `items[].event_id` | `string` | Yes | The search's id, unique within its session. | — |
| `items[].filtered` | `boolean` | Yes | The search applied a filter. A filter whose name starts with `_` is the client's own bookkeeping and never counts. | — |
| `items[].no_results` | `boolean` | Yes | The search returned nothing and was not redirected. | — |
| `items[].occurred_at` | `string` | Yes | When the search ran, in UTC. | format: date-time |
| `items[].platform` | `anyOf(string, null)` | Yes | Platform: `ios`, `android`, `windows`, …; `null` when unknown. | — |
| `items[].query` | `string` | Yes | The query, lowercased and trimmed. | — |
| `items[].redirected` | `boolean` | Yes | A redirect rule sent the search elsewhere. | — |
| `items[].session_id` | `string` | Yes | The session the search belongs to. | — |
| `items[].touchpoint` | `string` | Yes | Where the list was shown, as a request may cover several. | allowed values: autocomplete, serp |
| `items[].url` | `anyOf(string, null)` | Yes | The page the search ran on, with its query string; `null` when unknown. | — |
| `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": [
    {
      "applied_filters": [
        {
          "name": "example",
          "value": "example"
        }
      ],
      "channel_id": "example",
      "device": "example",
      "event_id": "example",
      "filtered": true,
      "no_results": true,
      "occurred_at": "2026-04-15T12:00:00Z",
      "platform": "example",
      "query": "example",
      "redirected": true,
      "session_id": "example",
      "touchpoint": "autocomplete",
      "url": "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"
}
```