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

Page aggregation

POST /v1/pages/aggregate

Counts pages matching a filter and groups them by categorical fields. Supports the count function, groupBy grouping and the numeric functions sum/avg/min/max over fields of type number (for example, views).

Request fields (body)

Parameter Type Required Description
Parameteraggregate Typearray Requiredno DescriptionArray of aggregations. Counting — { "field": "*", "function": "count" }. The sum/avg/min/max functions accept fields of type number: the metric among them is views; the rest (id, siteId, tplId, version and others) are identifiers. Without this parameter, the count of records matching the filter is returned
ParametergroupBy Typestring | array Requiredno DescriptionField or fields to group by. Only fields from aggregatable are allowed: siteId, active, deleted, public, folderId, tplId, createdById, modifiedById. Up to 5 fields
Parameterfilter Typeobject Requiredno DescriptionFiltering by page fields.
Filtering syntax. Example: { "siteId": 12 }

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/pages/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "groupBy": "siteId"
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/pages/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "groupBy": "siteId"
  }'

JavaScript — personal key

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

const { success, data } = await res.json()
console.log('Pages by site:', data.groups)

JavaScript — OAuth application

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

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

Other scenarios

Total number of pages in the Bitrix24 account — without fetching records:

JSON 
{}

Number of pages for a single site:

JSON 
{ "filter": { "siteId": 12 } }

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.count Typenumber DescriptionNumber of pages matching the filter
Fielddata.aggregates Typeobject DescriptionResults of numeric aggregations — over fields of type number (for example, views). An empty object when no aggregate array is passed
Fielddata.groups Typearray DescriptionPresent with groupBy. Each element is a dimension value plus the count of records in the group
Fielddata.meta.totalRecords Typenumber DescriptionTotal number of records
Fielddata.meta.recordsProcessed Typenumber DescriptionHow many records were processed
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 DescriptionPresent with groupBy — the number of groups
Fielddata.meta.groupsTruncated Typeboolean DescriptionPresent with groupBy. true if the number of groups exceeded the limit and the group list was truncated

Response example

Grouping by site (groupBy: "siteId"):

JSON 
{
  "success": true,
  "data": {
    "count": 84,
    "aggregates": {},
    "groups": [
      { "siteId": 12, "count": 9, "aggregates": {} },
      { "siteId": 14, "count": 6, "aggregates": {} },
      { "siteId": 27, "count": 11, "aggregates": {} }
    ],
    "meta": {
      "totalRecords": 84,
      "recordsProcessed": 84,
      "truncated": false,
      "groupTotal": 5,
      "groupsTruncated": false
    }
  }
}

Simple count without grouping ({}):

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

Error response example

400 — field outside the aggregatable list:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "groupBy field 'title' is not aggregatable on this entity. Available: siteId, active, deleted, public, folderId, tplId, createdById, modifiedById."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionThe groupBy field is outside the aggregatable list, or an unknown aggregation function
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the landing 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

Grouping is computed over the records that were read. When a response arrives with meta.truncated: true, the group counts are computed over the slice that was read, while the top-level count remains the exact total for the filter.

Visibility by user permissions. Only pages the API key owner has the "view" permission for are included in the count. If a non-zero result is expected but count is zero — check the permissions of the user the key was issued for.

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. For full details, see Aggregation POST — the 5000-record ceiling.

See also