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

Count of pipelines and numeric aggregates by filter. 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 if more than 5000 records matched the filter

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

Full list of common API errors — Errors.

See also