[{"data":1,"prerenderedAt":7},["ShallowReactive",2],{"docs-entities\u002Fcatalog-products\u002Faggregate":3,"docs-tabs-entities\u002Fcatalog-products\u002Faggregate":6},{"content":4,"lastmod":5},"\n## Aggregate catalog products\n\n`POST \u002Fv1\u002Fcatalog-products\u002Faggregate`\n\nCounting and numeric aggregations (sum, average, minimum, maximum) over catalog products with filtering and grouping via `groupBy`.\n\nThe `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.\n\n**Fields available for aggregation:**\n\n- `purchasingPrice`\n- `quantity`\n- `iblockSectionId`\n\n## Request fields (body)\n\n| Parameter | Type | Required | Description |\n|----------|-----|:-----:|---------|\n| `filter` | object | yes | Filtering by product fields. The `iblockId` key is required — the catalog from [`GET \u002Fv1\u002Fcatalogs`](\u002Fdocs\u002Fentities\u002Fcatalogs).\u003Cbr>[Filtering syntax](\u002Fdocs\u002Ffiltering) |\n| `aggregate` | array | no | Aggregations: `[{ \"field\": \"purchasingPrice\", \"function\": \"sum\" }]`. Functions: `sum`, `avg`, `min`, `max`, `count`. For `count`, the field is `\"*\"`. Without the parameter — `count` only |\n| `groupBy` | string \\| string[] | no | Field or array of fields to group by (up to 5). Values — from the list above |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcatalog-products\u002Faggregate\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"filter\": { \"iblockId\": 25 },\n    \"aggregate\": [\n      { \"field\": \"purchasingPrice\", \"function\": \"sum\" },\n      { \"field\": \"purchasingPrice\", \"function\": \"avg\" }\n    ],\n    \"groupBy\": \"iblockSectionId\"\n  }'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcatalog-products\u002Faggregate\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"filter\": { \"iblockId\": 25 },\n    \"aggregate\": [\n      { \"field\": \"purchasingPrice\", \"function\": \"sum\" },\n      { \"field\": \"purchasingPrice\", \"function\": \"avg\" }\n    ],\n    \"groupBy\": \"iblockSectionId\"\n  }'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcatalog-products\u002Faggregate', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    filter: { iblockId: 25 },\n    aggregate: [\n      { field: 'purchasingPrice', function: 'sum' },\n      { field: 'purchasingPrice', function: 'avg' },\n    ],\n    groupBy: 'iblockSectionId',\n  }),\n})\n\nconst { success, data } = await res.json()\nconsole.log(data.groups)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcatalog-products\u002Faggregate', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    filter: { iblockId: 25 },\n    aggregate: [\n      { field: 'purchasingPrice', function: 'sum' },\n      { field: 'purchasingPrice', function: 'avg' },\n    ],\n    groupBy: 'iblockSectionId',\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\nTo group by several fields, pass an array: `\"groupBy\": [\"iblockSectionId\", \"quantity\"]` (maximum 5 fields).\n\n## Other scenarios\n\nCount records — `count` with field `\"*\"`, the fastest request without fetching records. For a catalog, the `iblockId` filter is required:\n\n```json\n{ \"aggregate\": [{ \"field\": \"*\", \"function\": \"count\" }], \"filter\": { \"iblockId\": 25 } }\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | Always `true` on success |\n| `data.count` | number | Total number of products matching the filter |\n| `data.aggregates` | object | Aggregation results: `{ \"purchasingPrice\": { \"sum\": 0, \"avg\": 0 } }` |\n| `data.groups` | array | Groups — present only with `groupBy`. Each element: grouping fields + `count` + `aggregates` |\n| `data.meta.totalRecords` | number | Total number of records |\n| `data.meta.recordsProcessed` | number | Number of processed records (up to 5000). For a request without numeric functions — `0` |\n| `data.meta.truncated` | boolean | `true` 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` |\n| `data.meta.groupTotal` | number | Number of groups. Present only with `groupBy` |\n| `data.meta.groupsTruncated` | boolean | `true` if the number of groups was limited. Present only with `groupBy` |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"count\": 19,\n    \"aggregates\": {\n      \"purchasingPrice\": { \"sum\": 22120, \"avg\": 3686.67 }\n    },\n    \"groups\": [\n      {\n        \"iblockSectionId\": 19,\n        \"count\": 2,\n        \"aggregates\": { \"purchasingPrice\": { \"sum\": 0, \"avg\": 0 } }\n      },\n      {\n        \"iblockSectionId\": null,\n        \"count\": 15,\n        \"aggregates\": { \"purchasingPrice\": { \"sum\": 120, \"avg\": 60 } }\n      },\n      {\n        \"iblockSectionId\": 85,\n        \"count\": 2,\n        \"aggregates\": { \"purchasingPrice\": { \"sum\": 22000, \"avg\": 11000 } }\n      }\n    ],\n    \"meta\": {\n      \"totalRecords\": 19,\n      \"recordsProcessed\": 19,\n      \"truncated\": false,\n      \"groupTotal\": 3,\n      \"groupsTruncated\": false\n    }\n  }\n}\n```\n\nWithout `groupBy`, the `data.groups` field is absent from the response.\n\n## Error response example\n\n400 — a field outside the list available for aggregation:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INVALID_PARAMS\",\n    \"message\": \"groupBy field 'nonexistent' is not aggregatable on this entity. Available: purchasingPrice, quantity, iblockSectionId.\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `MISSING_REQUIRED_FILTER` | The required `filter[iblockId]` was not passed — checked before the Bitrix24 call (an example body is in the message) |\n| 400 | `UNKNOWN_FILTER_FIELD` | Unknown filter field or a date field: `dateCreate`, `timestampX`, `dateActiveFrom`, `dateActiveTo`. The message contains the list of available fields |\n| 400 | `INVALID_PARAMS` | The `groupBy` field is outside the available list — the message lists the allowed ones |\n| 400 | `INVALID_PARAMS` | A numeric function over an unknown field — `Field '\u003Cname>' not found. Available numeric fields: ...` |\n| 400 | `INVALID_PARAMS` | More than 5 fields passed in `groupBy` |\n| 403 | `SCOPE_DENIED` | The API key does not have the `catalog` scope |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not passed |\n| 429 | `RATE_LIMITED` | Rate 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 |\n\nFor the full list of common API errors, see [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**`count` is resolved in one request, numeric functions are not.** `count` is computed in a single 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 the 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. 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`.\n\n**Fields for grouping and for computation.** In `groupBy`, it makes sense to pass `iblockSectionId` — the catalog section. The numeric fields `purchasingPrice` and `quantity` support `sum`, `avg`, `min`, `max`.\n\n**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](\u002Fdocs\u002Fentity-api#aggregation-post-the-5000-record-ceiling).\n\n## See also\n\n- [List catalog products](\u002Fdocs\u002Fentities\u002Fcatalog-products\u002Flist)\n- [Search catalog products](\u002Fdocs\u002Fentities\u002Fcatalog-products\u002Fsearch)\n- [Catalog product fields](\u002Fdocs\u002Fentities\u002Fcatalog-products\u002Ffields)\n- [Filtering syntax](\u002Fdocs\u002Ffiltering)\n- [Limits and optimization](\u002Fdocs\u002Foptimization)\n","2026-10-23",{},1794739334171]