Aggregate items

POST /v1/items/:entityTypeId/aggregate

Count, sum, average, minimum, and maximum over smart process items with filtering and grouping. The smart process is specified in the path via entityTypeId — the process type ID, which you can obtain from GET /v1/smart-processes.

Standard fields:

• opportunity — item amount (suitable for numeric aggregation)
• categoryId — category (for groupBy)
• assignedById — responsible person (for groupBy)
• stageId — stage (for groupBy)
• createdBy — created by (for groupBy)
• updatedBy — last modified by (for groupBy)

User fields (UF): UF field names are prefixed with the smart process's internal type number — ufCrm<typeId>_* (for example, ufCrm7_1652689362). This number is not equal to the entityTypeId from the path — get the exact UF field names from the response of GET /v1/items/:entityTypeId/fields or from the INVALID_PARAMS error text, which lists your Bitrix24 account's available fields. Types integer, double, and money work with numeric functions; UF fields of any type work with groupBy. UF fields are the main source of business data in smart processes.

Use the entityTypeId field from GET /v1/smart-processes in the /v1/items/:entityTypeId path. The type record's internal id is a different identifier. For example, if a type is returned as { "id": 3, "entityTypeId": 174 }, the path starts with /v1/items/174. Use the returned value rather than assuming all type IDs start at 1030.

Path parameters

Request fields (body)

Examples

curl — personal key

curl -X POST "https://vibecode.bitrix24.com/v1/items/177/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "aggregate": [
      { "field": "opportunity", "function": "sum" },
      { "field": "opportunity", "function": "avg" }
    ],
    "filter": { "categoryId": 7 },
    "groupBy": "stageId"
  }'

curl — OAuth application

curl -X POST "https://vibecode.bitrix24.com/v1/items/177/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "aggregate": [
      { "field": "opportunity", "function": "sum" },
      { "field": "opportunity", "function": "avg" }
    ],
    "filter": { "categoryId": 7 },
    "groupBy": "stageId"
  }'

JavaScript — personal key

const entityTypeId = 177

const res = await fetch(`https://vibecode.bitrix24.com/v1/items/${entityTypeId}/aggregate`, {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    aggregate: [
      { field: 'opportunity', function: 'sum' },
      { field: 'opportunity', function: 'avg' },
    ],
    filter: { categoryId: 7 },
    groupBy: 'stageId',
  }),
})

const { success, data } = await res.json()
console.log('Total items:', data.count)
console.log('By stage:', data.groups)

JavaScript — OAuth application

const entityTypeId = 177

const res = await fetch(`https://vibecode.bitrix24.com/v1/items/${entityTypeId}/aggregate`, {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    aggregate: [
      { field: 'opportunity', function: 'sum' },
      { field: 'opportunity', function: 'avg' },
    ],
    filter: { categoryId: 7 },
    groupBy: 'stageId',
  }),
})

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

To group by multiple fields, pass an array: "groupBy": ["stageId", "categoryId"] (maximum 5).

Other scenarios

Count records — count with field "*", the fastest request without fetching records. Without the aggregate array the result is the same:

{ "aggregate": [{ "field": "*", "function": "count" }] }

Working with user fields (UF) — sum over a UF + grouping by another UF:

{
  "aggregate": [{ "field": "ufCrm7_1741091916816", "function": "sum" }],
  "groupBy": "ufCrm7_1652689362"
}

Response fields

Response example

Response to the main request (aggregations + groupBy: "stageId"):

{
  "success": true,
  "data": {
    "count": 14,
    "aggregates": {
      "opportunity": { "sum": 65911, "avg": 4707.92 }
    },
    "groups": [
      {
        "stageId": "DT177_7:NEW",
        "count": 8,
        "aggregates": { "opportunity": { "sum": 40000 } }
      },
      {
        "stageId": "DT177_7:SUCCESS",
        "count": 6,
        "aggregates": { "opportunity": { "sum": 25911 } }
      }
    ],
    "meta": {
      "totalRecords": 14,
      "recordsProcessed": 14,
      "truncated": false,
      "groupTotal": 2,
      "groupsTruncated": false
    }
  }
}

Without groupBy, the data.groups field is absent from the response.

Error response example

400 — reserved entityTypeId (for standard CRM entities):

{
  "success": false,
  "error": {
    "code": "INVALID_DYNAMIC_PARAM",
    "message": "entityTypeId 2 has a dedicated API: use /v1/deals instead"
  }
}

Errors

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

Known specifics

Without the aggregate array — only count. If you do not pass aggregate, the method makes one fast call to Bitrix24 and returns the count of records matching the filter. Suitable for dashboard counters.

Multiple aggregations in one request. You can combine them in a single call: [{ "field": "opportunity", "function": "sum" }, { "field": "opportunity", "function": "avg" }].

Money fields. UF fields of type money are stored in the format "amount|currency" ("1500|USD") — the aggregate extracts the numeric part automatically, so you can sum them without parsing.

Filtering by UF works. In filter you can pass any fields — standard and custom, of any type. For example, { "filter": { "ufCrm7_1652689362": 1435 } } returns the count of items with that UF value.

5000-record limit. Numeric aggregations load records page by page and compute the result on the Vibecode side. If more than 5000 records match the filter, the result is flagged with meta.truncated: true — only the first 5000 are taken. For an exact count use count (it works at any volume) or narrow the filter. 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.

Reserved entityTypeId. The values 1 (leads), 2 (deals), 3 (contacts), 4 (companies), 7 (quotes), 31 (invoices) are served by dedicated APIs — use /v1/deals/aggregate, /v1/leads/aggregate, /v1/contacts/aggregate, /v1/companies/aggregate, /v1/quotes/aggregate, /v1/invoices/aggregate.

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

• Smart process list
• Item list
• Item search
• Smart process item fields
• Filtering syntax
• Limits and optimization