## Aggregate Open Channel configurations

`POST /v1/openline-configs/aggregate`

Counts the number of Open Channel configurations with optional grouping by queue type and other schema fields.

**Grouping.** `groupBy` accepts 2 fields: `active`, `queueType` — these are the `aggregatable` fields from [`GET /v1/openline-configs/fields`](/docs/openlines/config/fields). The remaining fields (`id`, `name`, `workTimeFrom`, `workTimeTo`, and other camelCase response fields) are rejected in `groupBy` with `400 INVALID_PARAMS` — details in [Known specifics](#known-specifics).

**Numeric aggregations (`sum`/`avg`/`min`/`max`) do not apply.** The openline-configs fields are categorical or identifier fields; only the `count` function with `field: "*"` is supported.

## Request fields (body)

| Parameter | Type | Req. | Description |
|----------|-----|:-----:|---------|
| `aggregate` | array | no | Array of aggregations. Each element: `{ "field": "*", "function": "count" }`. The `count` function requires `field: "*"`. Without the parameter — only `count` |
| `filter` | object | no | Filtering. [Filtering syntax](/docs/filtering). Example: `{"active": false}` |
| `groupBy` | string \| string[] | no | Field or array of fields to group by. Allowed values: `active`, `queueType` — see [Known specifics](#known-specifics) |

## Examples

### curl — personal key

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/openline-configs/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "groupBy": "queueType"
  }'
```

### curl — OAuth application

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/openline-configs/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "groupBy": "queueType"
  }'
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/openline-configs/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    groupBy: 'queueType',
  }),
})

const { success, data } = await res.json()
console.log('Total configurations:', data.count)
console.log('By queue type:', data.groups)
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/openline-configs/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    groupBy: 'queueType',
  }),
})

const { success, data } = await res.json()
```

> To group by multiple fields, pass an array: `"groupBy": ["queueType", "active"]`. Combinations of the 2 allowed fields are accepted: `active`, `queueType`.

## Other scenarios

The total number of configurations — the fastest query, without fetching records:

```json
{}
```

Passing `count` explicitly via `aggregate`:

```json
{
  "aggregate": [{ "field": "*", "function": "count" }]
}
```

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data.count` | number | Total number of configurations in the selection (after applying the filter, if it took effect). This is the primary metric for an application |
| `data.aggregates` | object | Aggregation results (for openline-configs always `{}`) |
| `data.groups` | array | Groups (only when `groupBy` is set). Each element: the grouping field + `count` + `aggregates` |
| `data.meta.totalRecords` | number | How many records the aggregator saw in the input selection. Without `groupBy` it matches `data.count`; with `groupBy` it equals the sum of `count` across all groups. A technical metric |
| `data.meta.recordsProcessed` | number | How many records were actually processed during grouping. `0` if `groupBy` is not set |
| `data.meta.truncated` | boolean | `true` if more than 5000 records fell into the selection |
| `data.meta.groupTotal` | number | Number of groups in the result (only when `groupBy` is set) |
| `data.meta.groupsTruncated` | boolean | Flag indicating the group list was truncated (only when `groupBy` is set) |

## Response example

Response to the main query (`groupBy: "queueType"`):

```json
{
  "success": true,
  "data": {
    "count": 10,
    "aggregates": {},
    "groups": [
      { "queueType": "all", "count": 9, "aggregates": {} },
      { "queueType": "evenly", "count": 1, "aggregates": {} }
    ],
    "meta": {
      "totalRecords": 10,
      "recordsProcessed": 10,
      "truncated": false,
      "groupTotal": 2,
      "groupsTruncated": false
    }
  }
}
```

Without `groupBy` the `data.groups` field is absent from the response.

## Error response example

400 — the `count` function with an invalid field name:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "count aggregate requires field \"*\""
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | The `count` function was passed with `field` not equal to `"*"`, or `groupBy` was passed on a field outside the Vibecode schema |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |
| 403 | `SCOPE_DENIED` | The API key lacks the `imopenlines` scope |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

**The `filter` parameter is ignored in aggregate.** Passing `{"filter": {"active": false}}` has no effect on the result — the method returns the `count` across all configurations in your Bitrix24 account. Reason: aggregate iterates over records via the list method `imopenlines.config.list.get`, which on the Bitrix24 side does not apply a filter for openline-configs. To count by a subset, use `groupBy` (for example, `groupBy: ["active"]` splits the result by the activity flag) or process the result of [`POST /v1/openline-configs/search`](/docs/openlines/config/search) on the client side.

**The `count` function requires `field: "*"`.** Passing `{"field": "id", "function": "count"}` returns `400 INVALID_PARAMS`. The only correct format: `{"field": "*", "function": "count"}`.

**`groupBy` accepts only 2 fields from the Vibecode schema:** `active`, `queueType`. These are the `aggregatable` fields from the [`GET /v1/openline-configs/fields`](/docs/openlines/config/fields) response. The remaining fields (`id`, `name`, `workTimeFrom`, `workTimeTo`, `queueTime`, `crm`, ...) are rejected in `groupBy` with `400 INVALID_PARAMS` and the message "groupBy field 'X' is not aggregatable on this entity. Available: active, queueType".

## See also

- [List configurations](/docs/openlines/config/list) — get records with filtering and `total`
- [Filtering syntax](/docs/filtering)
- [Limits and optimization](/docs/optimization) — rate limits