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

Site aggregation

POST /v1/sites/aggregate

Counts sites 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 sites only { "field": "*", "function": "count" } is meaningful — the entity has no numeric metric 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: type, active, deleted, lang, tplId, domainId, createdById, modifiedById. Up to 5 fields
groupOrderBy array no Group sorting: an array of { "field": "count" | "<dimension>", "direction": "asc" | "desc" }. Works only together with groupBy
groupLimit number no Limit on the number of returned groups (1..1000). Works only together with groupBy
filter object no Filtering by key site fields.
Filtering syntax
scope string no Internal landing scope: KNOWLEDGE / GROUP / MAINPAGE. Without this parameter, regular landing sites are counted

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

Terminal 
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

Terminal 
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

javascript 
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

javascript 
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 account — the fastest request, without fetching records:

JSON 
{}

Number of active landing sites:

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

Response fields

Field Type Description
success boolean Always true on success
data.count number Number of sites matching the filter
data.aggregates object Numeric aggregation results. Stays empty for sites — there are no numeric metric fields
data.groups array Present when groupBy is set. Each element is a dimension value plus the record count 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 capped (true for more than 5000 records)
data.meta.groupTotal number Present when groupBy is set — the number of groups
data.meta.groupsTruncated boolean Present when groupBy is set. true if the number of groups exceeded the limit and the list was truncated

Response example

Grouping by type (groupBy: "type"):

JSON 
{
  "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 ({}):

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

Error response example

400 — a field outside the aggregatable list:

JSON 
{
  "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

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) the group counts are based on a 5000-record sample, while the top-level count stays the exact total by 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.

See also