Site aggregation

POST /v1/sites/aggregate

Counts sites matching a filter and groups them by categorical fields. Supports the count function and groupBy grouping.

Request fields (body)

Type filter and area (scope). If you pass {"filter": {"type": "KNOWLEDGE"}} or "GROUP" without scope, Vibecode supplies the matching area itself (type=KNOWLEDGE → scope=KNOWLEDGE) — counting knowledge bases and group pages works without setting scope manually, the same way it does in list and search. An explicit scope wins. MAINPAGE is an area, not a site type (its sites have type VIBE), so it is not derived from the type filter: pass scope=MAINPAGE explicitly for home pages.

Examples

curl — personal key

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

curl — OAuth application

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

JavaScript — personal key

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

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

JavaScript — OAuth application

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

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

Other scenarios

Total number of sites in the Bitrix24 account — the fastest request, without fetching records:

{}

Number of active landing sites:

{ "filter": { "type": "PAGE", "active": true } }

Response fields

Response example

Grouping by type (groupBy: "type"):

{
  "success": true,
  "data": {
    "count": 18,
    "aggregates": {},
    "groups": [
      { "type": "PAGE", "count": 11, "aggregates": {} },
      { "type": "STORE", "count": 5, "aggregates": {} },
      { "type": "VIBE", "count": 2, "aggregates": {} }
    ],
    "meta": {
      "totalRecords": 18,
      "recordsProcessed": 18,
      "truncated": false,
      "groupTotal": 3,
      "groupsTruncated": false
    }
  }
}

Plain count without grouping ({}):

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

Error response example

400 — a field outside the aggregatable list:

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

Errors

Full list of common API errors — 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 stays the exact total for the filter.

Visibility by user permissions. Only sites the API key owner has "view" permission for are counted. If a non-zero result is expected but count is zero — check the permissions of the user the key is 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. Full details — Aggregation POST — the 5000-record ceiling.

See also

• List sites
• Search sites
• Filtering syntax
• Limits and optimization