Aggregate companies

POST /v1/companies/aggregate

Count, sum, average, minimum and maximum over companies with filtering and grouping.

Standard fields:

• revenue — annual revenue (numeric aggregation makes sense)
• typeId — company type (for groupBy)
• industry — industry (for groupBy)
• assignedById — assigned person (for groupBy)
• sourceId — source (for groupBy)

User fields (UF): UF fields of type integer, double, money — for numeric functions; UF of any type — for groupBy. The full list of UF fields for a specific Bitrix24 account is returned in the INVALID_PARAMS error text if you pass a non-existent name.

Request fields (body)

Examples

curl — personal key

curl -X POST "https://vibecode.bitrix24.com/v1/companies/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "aggregate": [
      { "field": "revenue", "function": "sum" },
      { "field": "revenue", "function": "avg" }
    ],
    "filter": { "typeId": "CUSTOMER" },
    "groupBy": "industry"
  }'

curl — OAuth application

curl -X POST "https://vibecode.bitrix24.com/v1/companies/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "aggregate": [
      { "field": "revenue", "function": "sum" },
      { "field": "revenue", "function": "avg" }
    ],
    "filter": { "typeId": "CUSTOMER" },
    "groupBy": "industry"
  }'

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/companies/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    aggregate: [
      { field: 'revenue', function: 'sum' },
      { field: 'revenue', function: 'avg' },
    ],
    filter: { typeId: 'CUSTOMER' },
    groupBy: 'industry',
  }),
})

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

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/companies/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    aggregate: [
      { field: 'revenue', function: 'sum' },
      { field: 'revenue', function: 'avg' },
    ],
    filter: { typeId: 'CUSTOMER' },
    groupBy: 'industry',
  }),
})

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

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

Other scenarios

To count records, use count with the field set to "*". This is the fastest request and does not fetch 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": "UF_CRM_BUDGET", "function": "sum" }],
  "groupBy": "UF_CRM_SEGMENT"
}

Response fields

Response example

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

{
  "success": true,
  "data": {
    "count": 60,
    "aggregates": {
      "revenue": { "sum": 3000000, "avg": 50000 }
    },
    "groups": [
      {
        "industry": "IT",
        "count": 35,
        "aggregates": { "revenue": { "sum": 2000000 } }
      },
      {
        "industry": "RETAIL",
        "count": 25,
        "aggregates": { "revenue": { "sum": 1000000 } }
      }
    ],
    "meta": {
      "totalRecords": 60,
      "recordsProcessed": 60,
      "truncated": false
    }
  }
}

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

Error response example

400 — invalid function name, non-existent field, or groupBy on a non-aggregatable field:

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Field 'foo' not found. Available numeric fields: id, revenue, assignedById, createdBy, leadId, webformId, updatedBy, entityTypeId."
  }
}

Errors

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

Known specifics

count vs numeric functions. count is computed with a single call to Bitrix24 regardless of data volume. The sum/avg/min/max functions fetch records page by page (maximum 5000) and compute on the Vibecode side — if more than 5000 records match the filter, meta.truncated will be true and the aggregation runs over the first 5000. For exact counts 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 format "amount|currency" ("1500|USD") — the aggregate extracts the numeric part automatically, so values can be summed without parsing.

Filtering by UF works. In filter you can pass any fields — both standard and user fields, of any type. For example, { "filter": { "ufCrm_1234": "value" } } returns the number of companies with that UF value.

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 companies
• Search companies
• Filtering syntax
• Limits and optimization