Aggregate services

POST /v1/catalog-services/aggregate

Counts the services of a product catalog with filtering and grouping by catalog section.

The dateCreate, timestampX, dateActiveFrom, and dateActiveTo fields are not accepted in filter: the request returns 400 UNKNOWN_FILTER_FIELD before calling Bitrix24. This endpoint does not support date-range filtering. Calculate aggregates for a specific period in your integration using records from the list endpoint, where these dates are available in select and responses.

Fields available for aggregation:

• iblockSectionId — catalog section, for groupBy

A service has no numeric fields whose sum or average carries meaning. The sum, avg, min, max functions accept identifier fields — id, iblockId, iblockSectionId, measure, vatId, createdBy, modifiedBy, type — and the sort order sort. The main scenario is counting services with count, including by section.

Request fields (body)

Examples

curl — personal key

curl -X POST "https://vibecode.bitrix24.com/v1/catalog-services/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "iblockId": 25, "iblockSectionId": 281 },
    "groupBy": "iblockSectionId"
  }'

curl — OAuth application

curl -X POST "https://vibecode.bitrix24.com/v1/catalog-services/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "iblockId": 25, "iblockSectionId": 281 },
    "groupBy": "iblockSectionId"
  }'

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-services/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { iblockId: 25, iblockSectionId: 281 },
    groupBy: 'iblockSectionId',
  }),
})

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

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-services/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, iblockSectionId: 281 },
    groupBy: 'iblockSectionId',
  }),
})

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

groupBy also accepts an array: "groupBy": ["iblockSectionId"], up to 5 fields.

Other scenarios

The blocks below are request bodies.

Number of services in a catalog — a body without aggregate or groupBy, the fastest request, with no records fetched. The iblockId filter is required here too:

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

Number of services in each catalog section — services without a section are collected into a group with iblockSectionId: null:

{ "filter": { "iblockId": 25 }, "groupBy": "iblockSectionId" }

Response fields

Response example

{
  "success": true,
  "data": {
    "count": 2,
    "aggregates": {},
    "groups": [
      {
        "iblockSectionId": 281,
        "count": 2,
        "aggregates": {}
      }
    ],
    "meta": {
      "totalRecords": 2,
      "recordsProcessed": 2,
      "truncated": false,
      "groupTotal": 1,
      "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:

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

Errors

For the full list of common API errors, see Errors.

Known specifics

count is resolved in one request, grouping is not. count without groupBy is computed in a single call regardless of the size of the result set. groupBy and 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 is true, and the groups 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. For full details, see Aggregation POST — the 5000-record ceiling.

See also

• List services
• Search services
• Service fields
• Catalog sections
• Filtering syntax
• Limits and optimization