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

Aggregate workgroups

POST /v1/workgroups/aggregate

Count of workgroups, numeric aggregates, and grouping by filter. Without a request body it returns the total number of workgroups in a single call, without fetching records.

Standard fields:

  • membersCount — number of members (numeric aggregation makes sense)
  • active — activity flag (for groupBy)
  • isProject — project flag (for groupBy)
  • ownerId — workgroup owner (for groupBy)

Request fields (body)

Parameter Type Required Description
Parameteraggregate Typearray Requiredno DescriptionArray of aggregations. Numeric function: { "field": "membersCount", "function": "sum" }. Count function: { "field": "*", "function": "count" }. Functions: count, sum, avg, min, max. Without the array only count is returned
Parameterfilter Typeobject Requiredno DescriptionFiltering by fields from GET /v1/workgroups/fields. Filtering syntax
ParametergroupBy Typestring | string[] Requiredno DescriptionField or array of fields to group by (maximum 5). Allowed values — from the list above
ParametergroupOrderBy Typearray Requiredno DescriptionGroup sorting: [{ "field": "membersCount:sum", "direction": "desc" }]
ParametergroupLimit Typenumber Requiredno DescriptionLimit on the number of groups returned (1-1000)

The sum, avg, min, and max functions require a numeric field name, while count requires the "*" field. Numeric aggregation for workgroups makes sense on the membersCount field — the number of members.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/workgroups/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "aggregate": [
      { "field": "membersCount", "function": "sum" },
      { "field": "membersCount", "function": "avg" },
      { "field": "membersCount", "function": "min" },
      { "field": "membersCount", "function": "max" }
    ]
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/workgroups/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "aggregate": [
      { "field": "membersCount", "function": "sum" },
      { "field": "membersCount", "function": "avg" },
      { "field": "membersCount", "function": "min" },
      { "field": "membersCount", "function": "max" }
    ]
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/workgroups/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    aggregate: [
      { field: 'membersCount', function: 'sum' },
      { field: 'membersCount', function: 'avg' },
      { field: 'membersCount', function: 'min' },
      { field: 'membersCount', function: 'max' },
    ],
  }),
})

const { success, data } = await res.json()
console.log('Total members across all workgroups:', data.aggregates.membersCount.sum)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/workgroups/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    aggregate: [
      { field: 'membersCount', function: 'sum' },
      { field: 'membersCount', function: 'avg' },
      { field: 'membersCount', function: 'min' },
      { field: 'membersCount', function: 'max' },
    ],
  }),
})

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

Other scenarios

The total number of workgroups in the Bitrix24 account, the fastest request without fetching records:

JSON 
{}

Average workgroup size among projects:

JSON 
{
  "filter": { "isProject": true },
  "aggregate": [{ "field": "membersCount", "function": "avg" }]
}

Breakdown of the workgroup count by the activity flag:

JSON 
{
  "groupBy": "active"
}

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.count Typenumber DescriptionNumber of workgroups matching the filter
Fielddata.aggregates Typeobject DescriptionResults of numeric aggregations by field. Empty object if the aggregate array is not passed
Fielddata.groups Typearray DescriptionGroups (only with groupBy). Each element: the grouping fields, count, and aggregates
Fielddata.meta.totalRecords Typenumber DescriptionTotal number of workgroups matching the filter
Fielddata.meta.recordsProcessed Typenumber DescriptionHow many records were processed: 0 for a plain count, the number of records for numeric functions and for groupBy
Fielddata.meta.truncated Typeboolean Descriptiontrue 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
Fielddata.meta.groupTotal Typenumber DescriptionNumber of groups in the breakdown. Returned only with groupBy
Fielddata.meta.groupsTruncated Typeboolean DescriptionIndicates that some groups were omitted from the response. Returned only with groupBy

Response example

Numeric aggregates over the membersCount field:

JSON 
{
  "success": true,
  "data": {
    "count": 33,
    "aggregates": {
      "membersCount": {
        "sum": 65,
        "avg": 1.9696969696969697,
        "min": 0,
        "max": 7
      }
    },
    "meta": {
      "totalRecords": 33,
      "recordsProcessed": 33,
      "truncated": false
    }
  }
}

Grouping, body { "groupBy": "active" }:

JSON 
{
  "success": true,
  "data": {
    "count": 33,
    "aggregates": {},
    "groups": [
      {
        "active": true,
        "count": 33,
        "aggregates": {}
      }
    ],
    "meta": {
      "totalRecords": 33,
      "recordsProcessed": 33,
      "truncated": false,
      "groupTotal": 1,
      "groupsTruncated": false
    }
  }
}

Count request, body {}, records are not fetched and recordsProcessed is 0:

JSON 
{
  "success": true,
  "data": {
    "count": 33,
    "aggregates": {},
    "meta": {
      "totalRecords": 33,
      "recordsProcessed": 0,
      "truncated": false
    }
  }
}

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

Error response example

400 — the field passed in groupBy does not support grouping. The message contains the list of allowed fields:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "groupBy field 'name' is not aggregatable on this entity. Available: membersCount, active, isProject, ownerId."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionInvalid function name, a numeric function on a non-numeric field, groupBy over a non-aggregatable field, or more than 5 fields in groupBy
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the sonet_group scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP429 CodeRATE_LIMITED DescriptionRate 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

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

Known specifics

count vs numeric functions and grouping. count is computed in a single call at any volume — records are not fetched, recordsProcessed is 0, and the result matches the total field from List workgroups. The sum, avg, min, max functions and grouping via groupBy fetch records page by page and are computed on the platform side, so recordsProcessed equals the number of processed workgroups. When more than 5000 records match the filter, meta.truncated becomes true and the result is computed over the first 5000 — for an exact result on large result sets, 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.

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