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

Aggregate CRM products

POST /v1/products/aggregate

Counting and numeric aggregations — sum, average, minimum, maximum — over catalog products with filtering and grouping via groupBy.

Standard fields. The following are available for grouping and counting:

  • price — price. Supports numeric aggregation
  • sectionId — catalog section. For groupBy
  • catalogId — catalog identifier. For groupBy
  • active — active flag. For groupBy

Custom properties. Catalog properties of the form PROPERTY_<N> are not available for aggregation — use price for numeric functions, and sectionId, catalogId, or active to split into groups.

Request fields (body)

Parameter Type Required Description
Parameteraggregate Typearray Requiredno DescriptionAggregations: [{ "field": "price", "function": "sum" }]. Functions: sum, avg, min, max, count. For count, the field is "*". If omitted, only count is computed
Parameterfilter Typeobject Requiredno DescriptionFiltering by product fields.
Filtering syntax. Example: { "active": true }
ParametergroupBy Typestring | string[] Requiredno DescriptionA field or an array of fields to group by (up to 5). Values — price, sectionId, catalogId, active

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/products/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "aggregate": [
      { "field": "price", "function": "sum" },
      { "field": "price", "function": "avg" }
    ],
    "groupBy": "sectionId"
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/products/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "aggregate": [
      { "field": "price", "function": "sum" },
      { "field": "price", "function": "avg" }
    ],
    "groupBy": "sectionId"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/products/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    aggregate: [
      { field: 'price', function: 'sum' },
      { field: 'price', function: 'avg' },
    ],
    groupBy: 'sectionId',
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/products/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    aggregate: [
      { field: 'price', function: 'sum' },
      { field: 'price', function: 'avg' },
    ],
    groupBy: 'sectionId',
  }),
})

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

To group by several fields, pass an array: "groupBy": ["sectionId", "active"] (maximum 5 fields).

Other scenarios

Count records — count with the field "*", the fastest request, as it fetches no records. Omitting the aggregate array gives the same result:

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

Sum and average price across the whole catalog, without splitting into groups:

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.count Typenumber DescriptionTotal number of products matching the filter
Fielddata.aggregates Typeobject DescriptionAggregation results: { "price": { "sum": 0, "avg": 0 } }. When the response is computed over only some of the records, each field object carries truncated: true next to its numbers
Fielddata.groups Typearray DescriptionGroups — present only when groupBy is used. Each element: grouping fields + count + aggregates
Fielddata.groups[].truncated Typeboolean DescriptionPresent only when the response is computed over only some of the records, with the value true. The group's count is then the number of the group's records that were read, not of all of them
Fielddata.meta.totalRecords Typenumber DescriptionTotal number of records
Fielddata.meta.recordsProcessed Typenumber DescriptionNumber of processed records (up to 5000)
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 DescriptionPresent only when records are missing: how many records matching the filter did not make it into the numbers. Equals totalRecords - recordsProcessed
Fielddata.meta.pageErrorSample Typeobject DescriptionPresent only when reading the records was cut short by a page error. The numbers then cover the records read before it
Fielddata.meta.pageErrorSample.code Typestring DescriptionCode of the page error
Fielddata.meta.pageErrorSample.message Typestring DescriptionMessage of the page error
Fielddata.meta.warnings Typearray DescriptionPresent only when the response is computed over only some of the records: a single entry with the code AGGREGATE_TRUNCATED. data.count stays exact
Fielddata.meta.warnings[].code Typestring DescriptionWarning code — AGGREGATE_TRUNCATED
Fielddata.meta.warnings[].message Typestring DescriptionWarning text
Fielddata.meta.groupTotal Typenumber DescriptionNumber of groups. Present only when groupBy is used
Fielddata.meta.groupsTruncated Typeboolean Descriptiontrue if the number of groups was limited. Present only when groupBy is used

Response example

JSON 
{
  "success": true,
  "data": {
    "count": 19,
    "aggregates": {
      "price": { "sum": 68680, "avg": 5283.076923076923 }
    },
    "groups": [
      {
        "sectionId": null,
        "count": 15,
        "aggregates": { "price": { "sum": 2662, "avg": 295.77777777777777 } }
      },
      {
        "sectionId": 19,
        "count": 2,
        "aggregates": { "price": { "sum": 20, "avg": 10 } }
      },
      {
        "sectionId": 85,
        "count": 2,
        "aggregates": { "price": { "sum": 65998, "avg": 32999 } }
      }
    ],
    "meta": {
      "totalRecords": 19,
      "recordsProcessed": 19,
      "truncated": false,
      "groupTotal": 3,
      "groupsTruncated": false
    }
  }
}

Without groupBy, the data.groups field is absent from the response.

Error response example

400 — numeric function over a non-numeric field:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Field 'name' is not numeric (type: string). Only number fields support sum."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionUnknown aggregation function
HTTP400 CodeINVALID_PARAMS DescriptionNumeric function over a non-numeric field — the message names the field type
HTTP400 CodeINVALID_PARAMS DescriptionNon-existent field — the message lists the allowed numeric fields
HTTP400 CodeINVALID_PARAMS DescriptionThe groupBy field is not in the list price, sectionId, catalogId, active
HTTP400 CodeINVALID_PARAMS DescriptionMore than 5 fields passed in groupBy
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the crm scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed
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

count is resolved in a single request; numeric functions are not. count is computed in one call regardless of the size of the result set. The sum, avg, min, max functions load records page by page — up to 5000 — and compute values on the server side. If more than 5000 records match the filter, meta.truncated is true, and the aggregates and groups are built over the first 5000. For an exact count on large result sets, use count or narrow the filter. 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.

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

See also