Aggregate dictionary records

POST /v1/statuses/aggregate

Count (count) and numeric aggregations sum, avg, min, max over CRM dictionary records with a filter. The primary scenario is count: how many records are in a dictionary or match a filter.

Standard fields

Numeric functions apply to numeric fields of a record:

The fields entityId, statusId, name, semantics are categorical. Only count with a filter is available for them. Grouping via groupBy is not supported for dictionaries. CRM dictionaries have no user fields.

Request fields (body)

Examples

curl — personal key

curl -X POST "https://vibecode.bitrix24.com/v1/statuses/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "entityId": "DEAL_STAGE" }
  }'

curl — OAuth application

curl -X POST "https://vibecode.bitrix24.com/v1/statuses/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "entityId": "DEAL_STAGE" }
  }'

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/statuses/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { entityId: 'DEAL_STAGE' },
  }),
})

const { success, data } = await res.json()
console.log('Stages in the funnel:', data.count)

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/statuses/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { entityId: 'DEAL_STAGE' },
  }),
})

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

Other scenarios

Total number of records across all dictionaries — count without a filter:

{}

Range and average sort value of funnel stages — numeric functions over the sort field:

{
  "aggregate": [
    { "field": "sort", "function": "min" },
    { "field": "sort", "function": "max" },
    { "field": "sort", "function": "avg" }
  ],
  "filter": { "entityId": "DEAL_STAGE" }
}

The response to such a request contains a populated data.aggregates:

{
  "success": true,
  "data": {
    "count": 8,
    "aggregates": {
      "sort": { "min": 10, "max": 80, "avg": 45 }
    },
    "meta": { "totalRecords": 8, "recordsProcessed": 8, "truncated": false }
  }
}

Response fields

Response example

{
  "success": true,
  "data": {
    "count": 8,
    "aggregates": {},
    "meta": {
      "totalRecords": 8,
      "recordsProcessed": 0,
      "truncated": false
    }
  }
}

With numeric functions, the data.aggregates field is populated — see “Other scenarios”.

Error response example

400 — numeric function over a nonexistent field:

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Field 'nope' not found. Available numeric fields: id, sort, categoryId."
  }
}

Errors

For the full list of errors, see Errors.

Known specifics

count versus numeric functions. count is computed with a single call to Bitrix24 regardless of volume and does not download records — that is why data.meta.recordsProcessed equals 0. The functions sum / avg / min / max load records page by page and compute on the Vibecode side. If more than 5000 records match the filter, data.meta.truncated: true is returned and the result is calculated over the first 5000. The ceiling is not the only reason for this marker: it also appears when fewer records were read than data.count promised, and the size of the gap is reported in data.meta.recordsShortfall.

Grouping is not available. Dictionary fields are not part of the groupable set, so groupBy returns 400 INVALID_PARAMS. To count records by dictionary type, call count with the filter filter[entityId] separately for each type.

The truncation marker travels with the number itself. When a response arrives with meta.truncated: true, the marker truncated: true sits inside every field object in data.aggregates and on every element of data.groups, and data.meta.warnings gains a warning with the code AGGREGATE_TRUNCATED. A client that reads only the number itself therefore sees that it was computed over only some of the records. None of these markers appear on a complete response. Full details — Aggregation POST — the 5000-record ceiling.

See also

• List of dictionaries
• Search dictionary records
• Dictionary fields
• Filtering syntax
• Limits and optimization