For AI agents: markdown of this page — /docs-content-en/openlines/config/aggregate.md documentation index — /llms.txt

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. The remaining fields (id, name, workTimeFrom, workTimeTo, and other camelCase response fields) are rejected in groupBy with 400 INVALID_PARAMS — details in 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. Example: {"active": false}
groupBy string | string[] no Field or array of fields to group by. Allowed values: active, queueType — see Known specifics

Examples

curl — personal key

Terminal 
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

Terminal 
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.

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