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 with respect to a filter and groups them by categorical fields. Supports the count function and groupBy grouping.

Request fields (body)

Parameter Type Required Description
aggregate array no Array of aggregations. For pages only { "field": "*", "function": "count" } is meaningful — the entity has no numeric fields for sum/avg/min/max. Without this parameter, the record count matching the filter is returned
groupBy string | array no Field or fields to group by. Only fields from aggregatable are allowed: siteId, active, deleted, public, folderId, tplId, createdById, modifiedById. Up to 5 fields
filter object no Filtering 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
success boolean Always true on success
data.count number Number of pages matching the filter
data.aggregates object Results of numeric aggregations. For pages it stays empty — there are no numeric fields
data.groups array Present with groupBy. Each element is a dimension value plus the count of records in the group
data.meta.totalRecords number Total number of records
data.meta.recordsProcessed number How many records were processed
data.meta.truncated boolean Whether the result was limited (true for more than 5000 records)
data.meta.groupTotal number Present with groupBy — the number of groups
data.meta.groupsTruncated boolean Present 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
400 INVALID_PARAMS The groupBy field is outside the aggregatable list, or an unknown aggregation function
403 SCOPE_DENIED The API key lacks the landing scope
401 TOKEN_MISSING The API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

Grouping is computed over a sample. With more than 5000 records (meta.truncated: true), group counters are based on a sample of 5000 records, 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 under.

See also