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

Aggregate funnels

POST /v1/deal-categories/aggregate

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

Request fields (body)

Parameter Type Required Description
Parameteraggregate Typearray Requiredno DescriptionArray 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
Parameterfilter Typeobject Requiredno DescriptionExact match and $in on id, name, sort. Filtering by isLocked or createdAt returns 400 UNSUPPORTED_FILTER. Filtering syntax
ParametergroupBy Typestring or string[] Requiredno DescriptionA user-defined field name or an array of up to 5 user-defined field names returned by the fields endpoint. The schema has no standard grouping fields

Numeric functions (sum/avg/min/max) apply to numeric funnel fields — sort. The schema declares no standard fields for grouping. groupBy accepts user-defined fields returned by the fields endpoint; other fields return 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 funnels:', 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

To count records, use count with the field set to "*". This is the fastest request because it does not fetch records. Without the aggregate array the result is the same:

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

Sum of the sort field across all funnels:

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionAggregation result: record count, function values and selection details
Fielddata.count Typenumber DescriptionTotal number of funnels matching the filter
Fielddata.aggregates Typeobject DescriptionResults of numeric aggregations by field, in the form { "sort": { "sum": 2410 } }. Empty object if the aggregate array is not passed
Fielddata.meta.totalRecords Typenumber DescriptionTotal number of funnels matching the filter
Fielddata.meta.recordsProcessed Typenumber DescriptionHow many records were processed: 0 for a plain count, the number of records for numeric functions
Fielddata.meta.truncated Typeboolean Descriptiontrue 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
Fielddata.meta.recordsShortfall Typenumber DescriptionHow many funnels matching the filter were left out of the calculation: totalRecords minus recordsProcessed. Present only when fewer records were read than data.count promised
Fielddata.meta.pageErrorSample Typeobject DescriptionThe sub-page error that cut the slice short: code and message. Present only when the slice was cut short
Fielddata.meta.warnings Typearray DescriptionAn array with a single warning: code is AGGREGATE_TRUNCATED, message is the text. Present only together with data.meta.truncated: true

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 when no user-defined grouping fields were available:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "groupBy is not supported on this entity"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionUnsupported groupBy field or a numeric function on a non-numeric field
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the crm scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP429 CodeRATE_LIMITED DescriptionRate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the x-ratelimit-limit header. Retry after the delay in the Retry-After header

For the full list of common API errors, see 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 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. For full details, see Aggregation POST — the 5000-record ceiling.

See also