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 the number of smart process types by 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 the fields from the aggregatable list:

  • createdBy, updatedBy — who created and who last changed the type. Suitable for groupBy.
  • customSectionId — the custom workspace identifier. Suitable for groupBy.
  • isCategoriesEnabled, isStagesEnabled, isAutomationEnabled, isBizProcEnabled, isPaymentsEnabled, isCountersEnabled, isLinkWithProductsEnabled — capability flags.

The main scenario for the type catalog is 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 if more than 5000 types matched the filter
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

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.

See also