Для AI-агентов: markdown этой страницы — /docs-content/entities/sites/aggregate.md индекс документации — /llms.txt

Агрегация сайтов

POST /v1/sites/aggregate

Подсчёт количества сайтов с учётом фильтра и группировка по категориальным полям. Поддерживает функцию count и группировку groupBy.

Поля запроса (body)

Параметр Тип Обяз. Описание
aggregate array нет Массив агрегаций. Для сайтов осмысленна { "field": "*", "function": "count" } — числовых полей-метрик для sum/avg/min/max у сущности нет. Без параметра возвращается count записей с учётом фильтра
groupBy string | array нет Поле или поля для группировки. Допустимы только поля из aggregatable: type, active, deleted, lang, tplId, domainId, createdById, modifiedById. До 5 полей
groupOrderBy array нет Сортировка групп: массив { "field": "count" | "<измерение>", "direction": "asc" | "desc" }. Работает только вместе с groupBy
groupLimit number нет Ограничение числа возвращаемых групп (1..1000). Работает только вместе с groupBy
filter object нет Фильтрация по ключевым полям сайта.
Синтаксис фильтрации
scope string нет Внутренняя область лендингов: KNOWLEDGE / GROUP / MAINPAGE. Без параметра подсчитываются обычные сайты-лендинги

Фильтр по типу и область (scope). Если вы передали {"filter": {"type": "KNOWLEDGE"}} или "GROUP" без scope, Вайбкод сам подставит соответствующую область (type=KNOWLEDGE → scope=KNOWLEDGE) — подсчёт баз знаний и страниц групп работает без ручного указания scope, как в списке и поиске. Явный scope в приоритете. MAINPAGE — область, а не тип сайта (её сайты имеют тип VIBE), поэтому из фильтра по типу не выводится: для главных страниц передавайте scope=MAINPAGE явно.

Примеры

curl — личный ключ

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

curl — OAuth-приложение

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/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 — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/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('Сайтов по типу:', data.groups)

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/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()

Другие сценарии

Общее количество сайтов в портале — самый быстрый запрос, без выгрузки записей:

JSON 
{}

Количество активных сайтов-лендингов:

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

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.count number Количество сайтов, соответствующих фильтру
data.aggregates object Результаты числовых агрегаций. Для сайтов остаётся пустым — нет числовых полей-метрик
data.groups array Присутствует при groupBy. Каждый элемент — значение измерения плюс count записей в группе
data.meta.totalRecords number Общее количество записей
data.meta.recordsProcessed number Количество обработанных записей
data.meta.truncated boolean Был ли результат ограничен (true при более 5000 записей)
data.meta.groupTotal number Присутствует при groupBy — количество групп
data.meta.groupsTruncated boolean Присутствует при groupBy. true, если число групп превысило лимит и список групп усечён

Пример ответа

Группировка по типу (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
    }
  }
}

Простой подсчёт без группировки ({}):

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

Пример ответа при ошибке

400 — поле вне списка aggregatable:

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."
  }
}

Ошибки

HTTP Код Описание
400 INVALID_PARAMS Поле groupBy вне списка aggregatable или неизвестная функция агрегации
403 SCOPE_DENIED API-ключ не имеет скоупа landing
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

Полный список общих ошибок API — Ошибки.

Известные особенности

Группировка считается по выборке. При более 5000 записей (meta.truncated: true) счётчики групп основаны на выборке из 5000 записей, а верхний count остаётся точным общим числом по фильтру.

Видимость по правам пользователя. В подсчёт попадают только те сайты, к которым у владельца API-ключа есть право «просмотр». Если ожидается ненулевой результат, но count равен нулю — проверьте права пользователя, под которым выпущен ключ.

Смотрите также