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

Aggregate products

POST /v1/products/aggregate

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

Standard fields. Available for grouping and counting:

  • price — price. Numeric aggregation makes sense
  • sectionId — catalog section. For groupBy
  • catalogId — catalog identifier. For groupBy
  • active — activity. For groupBy

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

Request fields (body)

Parameter Type Required Description
aggregate array no Aggregations: [{ "field": "price", "function": "sum" }]. Functions: sum, avg, min, max, count. For count, the field is "*". Without the parameter — only count
filter object no Filtering by product fields.
Filtering syntax. Example: { "active": true }
groupBy string | string[] no A 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 app

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 app

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 field "*", the fastest request without fetching records. Without the aggregate array the result is the same:

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
success boolean Always true on success
data.count number Total number of products matching the filter
data.aggregates object Aggregation results: { "price": { "sum": 0, "avg": 0 } }
data.groups array Groups — present only when groupBy is used. 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)
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 when groupBy is used
data.meta.groupsTruncated boolean true 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
400 INVALID_PARAMS Unknown aggregation function
400 INVALID_PARAMS Numeric function over a non-numeric field — the message names the field type
400 INVALID_PARAMS Non-existent field — the message lists the allowed numeric fields
400 INVALID_PARAMS The groupBy field is outside the list price, sectionId, catalogId, active
400 INVALID_PARAMS More than 5 fields passed in groupBy
403 SCOPE_DENIED API key lacks the crm 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 a single request, numeric functions are not. count is computed in one call regardless of the selection size. 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 counter on large selections, use count or narrow the filter.

See also