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

Aggregate SKUs

POST /v1/catalog-skus/aggregate

Counts the parent products of a product catalog with filtering and grouping by section via groupBy.

Standard fields. One field is available for grouping — iblockSectionId, the catalog section. The numeric functions sum, avg, min, max accept fields of type number, but on a parent product these are identifiers, sort and type, so the main scenario here is a count with grouping.

Request fields (body)

Parameter Type Required Description
filter object yes Filtering by parent product fields. The iblockId key is required — the product catalog from GET /v1/catalogs. The type key accepts one exact number, 3 or 6.
Filtering syntax
aggregate array no Aggregations: [{ "field": "*", "function": "count" }]. Functions: count, sum, avg, min, max. 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). Allowed value — iblockSectionId

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-skus/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": "*", "function": "count" }],
    "groupBy": "iblockSectionId"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-skus/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { iblockId: 25 },
    aggregate: [{ field: '*', function: 'count' }],
    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-skus/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: '*', function: 'count' }],
    groupBy: 'iblockSectionId',
  }),
})

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

Other scenarios

The blocks below are request bodies.

Count parent products without grouping — the fastest request, no records are fetched:

JSON 
{ "filter": { "iblockId": 25 } }

Count parent products without offers — type equals 6:

JSON 
{ "filter": { "iblockId": 25, "type": 6 } }

Response fields

Field Type Description
success boolean Always true on success
data.count number Total number of parent products matching the filter
data.aggregates object Results of numeric functions by field: { "sort": { "max": 500 } }. Without numeric functions — an empty object
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 groupBy and numeric functions — 0
data.meta.truncated boolean true when the groups or 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
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": 14,
    "aggregates": {},
    "groups": [
      { "iblockSectionId": null, "count": 11, "aggregates": {} },
      { "iblockSectionId": 85, "count": 1, "aggregates": {} },
      { "iblockSectionId": 19, "count": 2, "aggregates": {} }
    ],
    "meta": {
      "totalRecords": 14,
      "recordsProcessed": 14,
      "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 grouping:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "groupBy field 'nonexistent' is not aggregatable on this entity. Available: 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 UNSUPPORTED_FILTER The filter.type key was passed as something other than one number, 3 or 6
400 INVALID_PARAMS The groupBy field is outside the available list — the message lists the allowed ones
400 INVALID_PARAMS A numeric function over a field that is not among the numeric fields of a parent product — the message lists them: Field '<name>' not found. Available numeric fields: ...
400 INVALID_PARAMS Unknown function — Invalid aggregate function '<name>'. Supported: count, sum, avg, min, max
400 INVALID_PARAMS More than 5 fields passed in groupBy
422 BITRIX_ERROR iblockId points to an offer catalog (productType is not allowed for this catalog)
403 SCOPE_DENIED The API key does not have the catalog scope
401 MISSING_API_KEY The X-Api-Key header was not passed
429 RATE_LIMITED Rate limit exceeded: 300 requests per minute per portal, all API keys of the portal share one limit. The exact value arrives in the x-ratelimit-limit header (the cap is divided across replicas). Retry after the delay in the Retry-After header

Full list of common API errors — Errors.

Known specifics

count is resolved in one request, grouping and numeric functions are not. A request without groupBy and numeric functions is counted in a single call regardless of the size of the result set. With groupBy or the sum, avg, min, max functions, records are loaded page by page — up to 5000 — and counted on the server side. If more than 5000 records match the filter, meta.truncated is true, and the groups and aggregates are built over the first 5000. 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. Full details — Aggregation POST — the 5000-record ceiling.

See also