# Recommender statistics breakdown

`POST /analytics/v1/channels/recommenders/stats/breakdown`

Aggregate breakdown statistics for recommenders across the requested channels.

## Request example

```bash
curl --request POST \
  --url 'https://api.eu1.luigisbox.ai/analytics/v1/channels/recommenders/stats/breakdown?channel_ids=<channel_ids>&interaction_mode=direct_conversions' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "consent_granted": true,
  "context_criteria": [
    {
      "attribute": "example",
      "operator": "in",
      "values": [
        "example"
      ]
    }
  ],
  "date_from": "2026-04-15T12:00:00Z",
  "date_to": "2026-04-15T12:00:00Z",
  "device": [
    "example"
  ],
  "external_ab_test_variant": [
    "example"
  ],
  "internal_ab_test_id": [
    "example"
  ],
  "internal_ab_test_variant": [
    "example"
  ],
  "is_personalized": true,
  "landing_page": [
    "example"
  ],
  "session_rank": {
    "exclude": false,
    "max": 1,
    "min": 1
  },
  "url_params": [
    {
      "attribute": "example",
      "operator": "in",
      "values": [
        "example"
      ]
    }
  ]
}'
```

## 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``). | — |
| `interaction_mode` | `string` | No | InteractionMode | allowed values: direct_conversions, direct_transactions |

## Request Body

**Required.**

### application/json

Schema: `object`

#### Attributes

| Attribute | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `consent_granted` | `anyOf(boolean, null)` | No | Consent Granted | — |
| `context_criteria` | `Array<anyOf(object, object)>` | No | Context Criteria | — |
| `context_criteria[].attribute` | `string` | Yes | Attribute | >= 1 characters |
| `context_criteria[].operator` | `string` | Yes | ComparisonOperator | allowed values: in, not_in, exists, not_exists, lt, lte, gt, gte, eq, neq |
| `context_criteria[].values` | `anyOf(Array<anyOf(string, number)>, null)` | No | Values | — |
| `date_from` | `string` | Yes | Date From | format: date-time |
| `date_to` | `anyOf(string, null)` | No | Date To | — |
| `device` | `Array<string>` | No | Device | — |
| `external_ab_test_variant` | `Array<string>` | No | External Ab Test Variant | — |
| `internal_ab_test_id` | `Array<string>` | No | Internal Ab Test Id | — |
| `internal_ab_test_variant` | `Array<string>` | No | Internal Ab Test Variant | — |
| `is_personalized` | `anyOf(boolean, null)` | No | Is Personalized | — |
| `landing_page` | `Array<string>` | No | Landing Page | — |
| `session_rank` | `anyOf(object, null)` | No | — | — |
| `session_rank.exclude` | `boolean` | No | Exclude | — |
| `session_rank.max` | `anyOf(integer, null)` | No | Max | — |
| `session_rank.min` | `anyOf(integer, null)` | No | Min | — |
| `url_params` | `Array<anyOf(object, object)>` | No | Url Params | — |
| `url_params[].attribute` | `string` | Yes | Attribute | >= 1 characters |
| `url_params[].operator` | `string` | Yes | ComparisonOperator | allowed values: in, not_in, exists, not_exists, lt, lte, gt, gte, eq, neq |
| `url_params[].values` | `anyOf(Array<anyOf(string, number)>, null)` | No | Values | — |

#### Request body example

```json
{
  "consent_granted": true,
  "context_criteria": [
    {
      "attribute": "example",
      "operator": "in",
      "values": [
        "example"
      ]
    }
  ],
  "date_from": "2026-04-15T12:00:00Z",
  "date_to": "2026-04-15T12:00:00Z",
  "device": [
    "example"
  ],
  "external_ab_test_variant": [
    "example"
  ],
  "internal_ab_test_id": [
    "example"
  ],
  "internal_ab_test_variant": [
    "example"
  ],
  "is_personalized": true,
  "landing_page": [
    "example"
  ],
  "session_rank": {
    "exclude": false,
    "max": 1,
    "min": 1
  },
  "url_params": [
    {
      "attribute": "example",
      "operator": "in",
      "values": [
        "example"
      ]
    }
  ]
}
```

## 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 | application/json: object |
| `503` | Service temporarily unavailable | application/json: object |
| `504` | Upstream timed out | application/json: object |

### 200

Successful Response

#### application/json

Schema: `object`

##### Attributes

| Attribute | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `global_stats` | `object` | Yes | Global stats breakdown of recommender metrics | — |
| `global_stats.clicks_level` | `object` | Yes | Recommender metrics at the clicks level | — |
| `global_stats.clicks_level.clicks` | `integer` | Yes | Clicks | — |
| `global_stats.clicks_level.sessions` | `integer` | Yes | Sessions | — |
| `global_stats.clicks_level.users` | `integer` | Yes | Users | — |
| `global_stats.interaction_mode` | `anyOf(string, null)` | Yes | — | — |
| `global_stats.interactions_level` | `object` | Yes | Recommender metrics at the interactions level | — |
| `global_stats.interactions_level.interactions` | `integer` | Yes | Interactions | — |
| `global_stats.interactions_level.sessions` | `integer` | Yes | Sessions | — |
| `global_stats.interactions_level.users` | `integer` | Yes | Users | — |
| `global_stats.list_level` | `object` | Yes | Recommender metrics at the list level | — |
| `global_stats.list_level.recommendations` | `integer` | Yes | Recommendations | — |
| `global_stats.list_level.sessions` | `integer` | Yes | Sessions | — |
| `global_stats.list_level.users` | `integer` | Yes | Users | — |
| `model_stats` | `Array<object>` | Yes | Model Stats | — |
| `model_stats[].clicks_level` | `object` | Yes | Recommender metrics at the clicks level | — |
| `model_stats[].clicks_level.clicks` | `integer` | Yes | Clicks | — |
| `model_stats[].clicks_level.sessions` | `integer` | Yes | Sessions | — |
| `model_stats[].clicks_level.users` | `integer` | Yes | Users | — |
| `model_stats[].interaction_mode` | `anyOf(string, null)` | Yes | — | — |
| `model_stats[].interactions_level` | `object` | Yes | Recommender metrics at the interactions level | — |
| `model_stats[].interactions_level.interactions` | `integer` | Yes | Interactions | — |
| `model_stats[].interactions_level.sessions` | `integer` | Yes | Sessions | — |
| `model_stats[].interactions_level.users` | `integer` | Yes | Users | — |
| `model_stats[].list_level` | `object` | Yes | Recommender metrics at the list level | — |
| `model_stats[].list_level.recommendations` | `integer` | Yes | Recommendations | — |
| `model_stats[].list_level.sessions` | `integer` | Yes | Sessions | — |
| `model_stats[].list_level.users` | `integer` | Yes | Users | — |
| `model_stats[].model` | `string` | Yes | Model | — |
| `widget_model_stats` | `Array<object>` | Yes | Widget Model Stats | — |
| `widget_model_stats[].clicks_level` | `object` | Yes | Recommender metrics at the clicks level | — |
| `widget_model_stats[].clicks_level.clicks` | `integer` | Yes | Clicks | — |
| `widget_model_stats[].clicks_level.sessions` | `integer` | Yes | Sessions | — |
| `widget_model_stats[].clicks_level.users` | `integer` | Yes | Users | — |
| `widget_model_stats[].interaction_mode` | `anyOf(string, null)` | Yes | — | — |
| `widget_model_stats[].interactions_level` | `object` | Yes | Recommender metrics at the interactions level | — |
| `widget_model_stats[].interactions_level.interactions` | `integer` | Yes | Interactions | — |
| `widget_model_stats[].interactions_level.sessions` | `integer` | Yes | Sessions | — |
| `widget_model_stats[].interactions_level.users` | `integer` | Yes | Users | — |
| `widget_model_stats[].list_level` | `object` | Yes | Recommender metrics at the list level | — |
| `widget_model_stats[].list_level.recommendations` | `integer` | Yes | Recommendations | — |
| `widget_model_stats[].list_level.sessions` | `integer` | Yes | Sessions | — |
| `widget_model_stats[].list_level.users` | `integer` | Yes | Users | — |
| `widget_model_stats[].model` | `string` | Yes | Model | — |
| `widget_model_stats[].widget_id` | `string` | Yes | Widget Id | — |

##### Response example

```json
{
  "global_stats": {
    "clicks_level": {
      "clicks": 1,
      "sessions": 1,
      "users": 1
    },
    "interaction_mode": "direct_conversions",
    "interactions_level": {
      "interactions": 1,
      "sessions": 1,
      "users": 1
    },
    "list_level": {
      "recommendations": 1,
      "sessions": 1,
      "users": 1
    }
  },
  "model_stats": [
    {
      "clicks_level": {
        "clicks": 1,
        "sessions": 1,
        "users": 1
      },
      "interaction_mode": "direct_conversions",
      "interactions_level": {
        "interactions": 1,
        "sessions": 1,
        "users": 1
      },
      "list_level": {
        "recommendations": 1,
        "sessions": 1,
        "users": 1
      },
      "model": "example"
    }
  ],
  "widget_model_stats": [
    {
      "clicks_level": {
        "clicks": 1,
        "sessions": 1,
        "users": 1
      },
      "interaction_mode": "direct_conversions",
      "interactions_level": {
        "interactions": 1,
        "sessions": 1,
        "users": 1
      },
      "list_level": {
        "recommendations": 1,
        "sessions": 1,
        "users": 1
      },
      "model": "example",
      "widget_id": "example"
    }
  ]
}
```

### 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

#### 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"
}
```

### 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"
}
```

### 504

Upstream timed out

#### 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"
}
```