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

Метод появляется в обновлении crm 26.2100.0 и пока доступен не на всех порталах Битрикс24. Если метод ещё не включён, API возвращает 422 METHOD_NOT_YET_AVAILABLE.

Получить дерево рекламы источника

GET /v1/crm-tracking/sources/:id/ad-tree

Получить одну страницу рекламных кампаний, групп объявлений или ключевых слов за выбранный период.

Нужны скоуп crm, включённый флаг crm-tracking-v3 и доступность метода на портале Битрикс24. Ключ READONLY может выполнять этот запрос.

Параметры

Параметр Тип Обяз. По умолч. Описание
Параметрid (path) Типinteger Обяз.да По умолч.— ОписаниеПоложительный ID источника из списка источников.
ПараметрdateFrom (query) Типstring Обяз.да По умолч.— ОписаниеНачало периода, YYYY-MM-DD.
ПараметрdateTo (query) Типstring Обяз.да По умолч.— ОписаниеКонец периода, YYYY-MM-DD.
Параметрlevel (query) Типstring Обяз.нет По умолч.campaign ОписаниеУровень: campaign, group или keyword.
ПараметрparentId (query) Типinteger Обяз.нет По умолч.— ОписаниеID родительского узла из data.items[].id этого метода.
Параметрcursor (query) Типstring Обяз.нет По умолч.— ОписаниеОбъект продолжения, закодированный как JSON. Первый запрос — без курсора.
Параметрcursor.field Типstring Обяз.да, в курсоре По умолч.id ОписаниеТолько id.
Параметрcursor.value Типstring Обяз.да, в курсоре По умолч.— ОписаниеНепустое значение data.cursor.value предыдущей страницы, до 4096 байт.
Параметрcursor.limit Типinteger Обяз.нет По умолч.50 ОписаниеРазмер страницы от 1 до 100.
Параметрcursor.order Типstring Обяз.нет По умолч.ASC ОписаниеТолько ASC.

При data.hasMore: true передайте полученный data.cursor в следующий запрос с теми же датами, уровнем и родительским узлом. API не обходит страницы автоматически. Параметр offset не поддерживается.

Примеры

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

Terminal 
curl --get "https://vibecode.bitrix24.tech/v1/crm-tracking/sources/42/ad-tree" \
  -H "X-Api-Key: YOUR_API_KEY" \
  --data-urlencode "dateFrom=2026-10-01" \
  --data-urlencode "dateTo=2026-10-07"

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

Terminal 
curl --get "https://vibecode.bitrix24.tech/v1/crm-tracking/sources/42/ad-tree" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  --data-urlencode "dateFrom=2026-10-01" \
  --data-urlencode "dateTo=2026-10-07"

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

javascript 
const query = new URLSearchParams({ dateFrom: '2026-10-01', dateTo: '2026-10-07' })
const res = await fetch(`https://vibecode.bitrix24.tech/v1/crm-tracking/sources/42/ad-tree?${query}`, {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})
const result = await res.json()
console.log(result)

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

javascript 
const query = new URLSearchParams({ dateFrom: '2026-10-01', dateTo: '2026-10-07' })
const res = await fetch(`https://vibecode.bitrix24.tech/v1/crm-tracking/sources/42/ad-tree?${query}`, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const result = await res.json()
console.log(result)

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean Описаниеtrue
Полеdata Типobject ОписаниеСтраница дерева рекламы.
Полеdata.items Типobject[] ОписаниеУзлы запрошенного уровня.
Полеdata.hasMore Типboolean ОписаниеЕсть ли следующая страница.
Полеdata.cursor Типobject ОписаниеКурсор продолжения.
Полеdata.cursor.field Типstring Описаниеid
Полеdata.cursor.value Типstring или null ОписаниеЗначение для следующего запроса. null в конце списка.
Полеdata.items[].id Типinteger ОписаниеID узла. Можно передать как parentId при чтении следующего уровня.
Полеdata.items[].code Типstring ОписаниеКод узла.
Полеdata.items[].enabled Типboolean ОписаниеАктивен ли узел.
Полеdata.items[].title Типstring ОписаниеНазвание узла.
Полеdata.items[].level Типinteger ОписаниеНомер уровня узла.
Полеdata.items[].nextLevel Типinteger или null ОписаниеНомер следующего уровня или null.
Полеdata.items[].prevLevel Типinteger или null ОписаниеНомер предыдущего уровня или null.
Полеdata.items[].impressions Типinteger ОписаниеЧисло показов.
Полеdata.items[].actions Типinteger ОписаниеЧисло действий.
Полеdata.items[].outcome Типinteger ОписаниеПоказатель результата рекламы.
Полеdata.items[].currencyId Типstring ОписаниеКод валюты денежных показателей.
Полеdata.items[].leads Типinteger ОписаниеЧисло лидов.
Полеdata.items[].deals Типinteger ОписаниеЧисло сделок.
Полеdata.items[].successDeals Типinteger ОписаниеЧисло успешных сделок.
Полеdata.items[].cost Типnumber ОписаниеРасходы.
Полеdata.items[].income Типnumber ОписаниеДоход.
Полеdata.items[].roi Типnumber ОписаниеРентабельность инвестиций.
Полеdata.items[].roiScale Типinteger ОписаниеШкала показателя roi.
Полеdata.items[].ctr Типnumber ОписаниеПоказатель кликабельности.
Полеdata.items[].cpc Типnumber ОписаниеСтоимость клика.

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

JSON 
{
  "success": true,
  "data": {
    "items": [],
    "hasMore": false,
    "cursor": {
      "field": "id",
      "value": null
    }
  }
}

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

404 — источник не найден:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Запись с ID = `0` не найдена"
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодINVALID_PARAMS ОписаниеНекорректный ID источника или тип поля. Курсор дерева должен быть JSON-объектом.
HTTP400 КодBITRIX_REST_V3_EXCEPTION_VALIDATION_REQUESTVALIDATIONEXCEPTION ОписаниеНе переданы даты либо Битрикс24 отклонил значения параметров. В том числе неверный уровень или курсор.
HTTP400 КодUNKNOWN_FILTER_FIELD ОписаниеНеизвестный параметр строки запроса.
HTTP400 КодCRM_TRACKING_AD_PROVIDER_UNSUPPORTED ОписаниеИсточник не поддерживает рекламную операцию.
HTTP404 КодENTITY_NOT_FOUND ОписаниеИсточник не найден.
HTTP403 КодSCOPE_DENIED ОписаниеУ ключа нет скоупа crm.
HTTP403 КодBITRIX_REST_V3_EXCEPTION_ACCESSDENIEDEXCEPTION ОписаниеНедостаточно прав на портале Битрикс24.
HTTP401 КодTOKEN_MISSING ОписаниеУ ключа не настроен доступ к Битрикс24.
HTTP422 КодMETHOD_NOT_YET_AVAILABLE ОписаниеФлаг выключен или метод ещё не включён на портале. error.release — crm 26.2100.0.
HTTP502 КодBITRIX_UNAVAILABLE ОписаниеБитрикс24 вернул ответ неверной структуры.

Другие коды отказов, статусы и сообщения Битрикс24 сохраняются. Общие ошибки API — Ошибки.

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