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

Aggregate pipelines

POST /v1/deal-categories/aggregate

Counts pipelines matching a filter and computes numeric aggregates over them. Without a request body it returns the total number of pipelines in a single call, without fetching records.

Request fields (body)

Parameter Type Required Description
aggregate array no Array of aggregations. Each element: { "field": "sort", "function": "sum" }. Functions: count, sum, avg, min, max. For count, the field is "*". Without the array only count is returned
filter object no Exact match and $in on id, name, sort. Filtering by isLocked or createdAt returns 400 UNSUPPORTED_FILTER. Filtering syntax

Numeric functions (sum/avg/min/max) apply to numeric pipeline fields — sort. Grouping (groupBy) is unavailable: pipelines have no categorical fields to group by. A request with groupBy returns 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/deal-categories/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

curl — OAuth application

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

JavaScript — personal key

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

const { success, data } = await res.json()
console.log('Total pipelines:', data.count)

JavaScript — OAuth application

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

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

Other scenarios

Count records — count with field "*", the fastest request without fetching records. Without the aggregate array the result is the same:

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

Sum of the sort field across all pipelines:

JSON 
{
  "aggregate": [{ "field": "sort", "function": "sum" }]
}

Response fields

Field Type Description
success boolean Always true on success
data.count number Total number of pipelines matching the filter
data.aggregates object Results of numeric aggregations by field. Empty object if the aggregate array is not passed
data.meta.totalRecords number Total number of pipelines matching the filter
data.meta.recordsProcessed number How many records were processed: 0 for a plain count, the number of records for numeric functions
data.meta.truncated boolean true when the numbers were computed over only some of the records that match the filter: fewer records were read than data.count promised — including when more than 5000 matched the filter — or the slice was cut short by a sub-page error. The size of the gap is reported in data.meta.recordsShortfall, the interrupted slice in data.meta.pageErrorSample. Always present, and false on a complete response. If the request has neither groupBy nor a numeric function, no records are fetched and the flag is always false

Response example

Count request (body {}):

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

Sum of the sort field (body { "aggregate": [{ "field": "sort", "function": "sum" }] }):

JSON 
{
  "success": true,
  "data": {
    "count": 6,
    "aggregates": { "sort": { "sum": 2410 } },
    "meta": {
      "totalRecords": 6,
      "recordsProcessed": 6,
      "truncated": false
    }
  }
}

Error response example

400 — groupBy was passed (pipelines have no fields to group by):

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "groupBy field 'isLocked' is not aggregatable on this entity. Available: ."
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS groupBy passed or a numeric function on a non-numeric field
403 SCOPE_DENIED The API key lacks the crm scope
401 TOKEN_MISSING The API key has no configured tokens
429 RATE_LIMITED Rate limit exceeded: 300 requests per minute per portal, all API keys of the portal share one limit. The exact value arrives in the x-ratelimit-limit header (the cap is divided across replicas). Retry after the delay in the Retry-After header

Full list of common API errors — Errors.

Known specifics

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