Aggregate employees

POST /v1/users/aggregate

Count employees with filtering:

• count — works on any request (with or without a filter).
• groupBy — by standard fields from the aggregation list (active, isAdmin, isOnline, departmentId, workPosition, personalGender, personalCity) and by user fields (UF) of any type.
• sum / avg / min / max — only for numeric-type UF fields: integer, double, money.

Request fields (body)

Examples

curl — personal key

curl -X POST "https://vibecode.bitrix24.com/v1/users/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "active": true }
  }'

curl — OAuth application

curl -X POST "https://vibecode.bitrix24.com/v1/users/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "active": true }
  }'

JavaScript — personal key

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

const { success, data } = await res.json()
console.log('Active employees:', data.count)

JavaScript — OAuth application

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

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

To group by several fields, pass an array: "groupBy": ["active", "workPosition"] (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" }] }

Distribution by activity status — how many employees are active, how many are deactivated:

{ "groupBy": "active" }

Grouping by the "Internal number" UF field:

{ "groupBy": "UF_PHONE_INNER" }

Sum over a numeric UF field with grouping:

{
  "aggregate": [{ "field": "UF_SALARY", "function": "sum" }],
  "groupBy": "UF_DEPARTMENT"
}

Response fields

Response example

Response to a count request without groupBy:

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

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

Error response example

400 — groupBy on a nonexistent field (the message contains the list of available standard and UF fields):

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "groupBy field 'nonexistent' is not aggregatable on this entity. Available: active, isAdmin, isOnline, departmentId, workPosition, personalGender, personalCity. User-defined: UF_DEPARTMENT (string), UF_PHONE_INNER (string), UF_EMPLOYMENT_DATE (string), UF_SKILLS (string), UF_INTERESTS (string), UF_LINKEDIN (string), UF_FACEBOOK (string)."
  }
}

Errors

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

Known specifics

count vs numeric functions. count is computed in a single Bitrix24 call regardless of data volume. sum/avg/min/max load records page by page (maximum 5000) and compute on the Vibecode side. With more than 5000 records matching the filter — meta.truncated: true, aggregation over the first 5000. For an exact count on large result sets — use count 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.

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

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

• List employees
• Employee fields
• Filtering syntax
• Limits and optimization