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

Aggregate products

POST /v1/catalog-products/aggregate

Count and numeric aggregations (sum, average, minimum, maximum) over catalog products with filtering and grouping via groupBy.

Fields available for aggregation:

  • purchasingPrice
  • quantity
  • iblockSectionId

Request fields (body)

Parameter Type Req. Description
filter object yes Filtering by product fields. The iblockId key is required — the catalog from GET /v1/catalogs.
Filtering syntax
aggregate array no Aggregations: [{ "field": "purchasingPrice", "function": "sum" }]. Functions: sum, avg, min, max, count. For count, the field is "*". Without the parameter — count only
groupBy string | string[] no Field or array of fields to group by (up to 5). Values — from the list above

Examples

curl — personal key

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

curl — OAuth application

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

JavaScript — personal key

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

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

JavaScript — OAuth application

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

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

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

Other scenarios

Count records — count with field "*", the fastest request without fetching records. The catalog requires the iblockId filter:

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

Response fields

Field Type Description
success boolean Always true on success
data.count number Total number of products matching the filter
data.aggregates object Aggregation results: { "purchasingPrice": { "sum": 0, "avg": 0 } }
data.groups array Groups — present only with groupBy. Each element: grouping fields + count + aggregates
data.meta.totalRecords number Total number of records
data.meta.recordsProcessed number Number of processed records (up to 5000). For a request without numeric functions — 0
data.meta.truncated boolean true if there are more than 5000 records — aggregation over the first 5000
data.meta.groupTotal number Number of groups. Present only with groupBy
data.meta.groupsTruncated boolean true if the number of groups was limited. Present only with groupBy

Response example

JSON 
{
  "success": true,
  "data": {
    "count": 19,
    "aggregates": {
      "purchasingPrice": { "sum": 22120, "avg": 3686.67 }
    },
    "groups": [
      {
        "iblockSectionId": 19,
        "count": 2,
        "aggregates": { "purchasingPrice": { "sum": 0, "avg": 0 } }
      },
      {
        "iblockSectionId": null,
        "count": 15,
        "aggregates": { "purchasingPrice": { "sum": 120, "avg": 60 } }
      },
      {
        "iblockSectionId": 85,
        "count": 2,
        "aggregates": { "purchasingPrice": { "sum": 22000, "avg": 11000 } }
      }
    ],
    "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 — a field outside the list available for aggregation:

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

Errors

HTTP Code Description
400 MISSING_REQUIRED_FILTER The required filter[iblockId] filter was not passed — checked before the Bitrix24 call (an example body is in the message)
400 INVALID_PARAMS The groupBy field is outside the available list — the message lists the allowed ones
400 INVALID_PARAMS A numeric function over an unknown field — Field '<name>' not found. Available numeric fields: ...
400 INVALID_PARAMS More than 5 fields passed in groupBy
403 SCOPE_DENIED The API key does not have the catalog scope
401 MISSING_API_KEY The X-Api-Key header was not passed

Full list of common API errors — Errors.

Known specifics

count is resolved in one request, numeric functions are not. count is computed in a single call regardless of the selection size. The sum, avg, min, max functions load records page by page — up to 5000 — and compute the values on the server side. If more than 5000 records match the filter, meta.truncated equals true, and the aggregates and groups are built over the first 5000.

Fields for grouping and for computation. It makes sense to pass iblockSectionId — the catalog section — in groupBy. The numeric fields purchasingPrice and quantity support sum, avg, min, max.

See also