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

Aggregating smart process types

POST /v1/smart-processes/aggregate

Counts smart process types matching a filter, with optional grouping. Computes how many types in the Bitrix24 account match a condition and breaks them down by the value of a chosen field — for example, how many types each employee created, or how many have a given capability enabled.

Aggregation fields

Grouping and numeric functions work on fields from the aggregatable list:

  • createdBy, updatedBy — who created the type and who last modified it. Suitable for groupBy.
  • customSectionId — the digital workplace identifier. Suitable for groupBy.
  • isCategoriesEnabled, isStagesEnabled, isAutomationEnabled, isBizProcEnabled, isPaymentsEnabled, isCountersEnabled, isLinkWithProductsEnabled — capability flags.

The main scenarios for the type catalog are count (how many types match the filter) and groupBy (a breakdown by field). Smart process types have no custom fields — only the standard fields listed above are aggregated.

Request fields (body)

Parameter Type Required Description
aggregate array no Array of aggregations. Each element: { "field": "*", "function": "count" }. count counts rows, not field values. Functions: count, sum, avg, min, max. Without the array, only count is returned
filter object no Filter by type fields. Field list: Type fields. Filtering syntax
groupBy string | string[] no A field or array of fields to group by (maximum 5). Accepts only fields from the aggregatable list above

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/smart-processes/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "isStagesEnabled": true },
    "groupBy": "createdBy"
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/smart-processes/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "isStagesEnabled": true },
    "groupBy": "createdBy"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/smart-processes/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { isStagesEnabled: true },
    groupBy: 'createdBy',
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/smart-processes/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { isStagesEnabled: true },
    groupBy: 'createdBy',
  }),
})

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

To group by several fields, pass an array: "groupBy": ["createdBy", "isStagesEnabled"] (maximum 5).

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" }] }

How many types have automation rules and triggers enabled:

JSON 
{ "filter": { "isAutomationEnabled": true } }

Response fields

Field Type Description
success boolean Always true on success
data.count number Number of types matching the filter
data.aggregates object Results of numeric functions. For a count grouping — an empty object
data.groups array Groups (only with groupBy). Each element: the grouping field + count + aggregates
data.meta.totalRecords number Total number of types matching the filter
data.meta.recordsProcessed number How many types were processed for the aggregation
data.meta.truncated boolean true when the numbers were computed over only some of the types that match the filter: fewer types 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 types are fetched and the flag is always false
data.meta.groupTotal number Number of groups (only with groupBy)
data.meta.groupsTruncated boolean true if the group list was truncated

Response example

Grouping by creator (groupBy: "createdBy"):

JSON 
{
  "success": true,
  "data": {
    "count": 7,
    "aggregates": {},
    "groups": [
      { "createdBy": 1, "count": 4, "aggregates": {} },
      { "createdBy": 835, "count": 2, "aggregates": {} },
      { "createdBy": 1013, "count": 1, "aggregates": {} }
    ],
    "meta": {
      "totalRecords": 7,
      "recordsProcessed": 7,
      "truncated": false,
      "groupTotal": 3,
      "groupsTruncated": false
    }
  }
}

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

Error response example

400 — field not available for grouping:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "groupBy field 'title' is not aggregatable on this entity. Available: customSectionId, createdBy, updatedBy, isCategoriesEnabled, isStagesEnabled, isAutomationEnabled, isBizProcEnabled, isPaymentsEnabled, isCountersEnabled, isLinkWithProductsEnabled."
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS Unknown function, non-existent field, or a field outside the aggregatable list — the message lists the available fields
401 TOKEN_MISSING The API key has no configured tokens
403 SCOPE_DENIED The API key does not have the crm scope
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 general API errors — Errors.

Known specifics

count is computed in a single call. A request without the aggregate array returns the number of types matching the filter in one call to Bitrix24, without fetching the records.

Grouping by a flag yields two groups — true and false. For example, groupBy: "isAutomationEnabled" splits the types into two groups: those with automation rules enabled and those without. If all types have the same flag value, the response will contain a single group.

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