For AI agents: markdown of this page — /docs-content-en/entities/crm-tracking/ad-tree-list.md documentation index — /llms.txt

The method ships in the crm 26.2100.0 update and is not yet available on all Bitrix24 accounts. If the method is not enabled yet, the API returns 422 METHOD_NOT_YET_AVAILABLE.

List the advertising tree of a source

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

Retrieve one page of advertising campaigns, ad groups, or keywords for a period.

Requires the crm scope, the crm-tracking-v3 flag, and method availability in the Bitrix24 account. A READONLY key can run this request.

Parameters

Parameter Type Required Default Description
Parameterid (path) Typeinteger Requiredyes Default— DescriptionPositive source ID from the source list.
ParameterdateFrom (query) Typestring Requiredyes Default— DescriptionPeriod start, YYYY-MM-DD.
ParameterdateTo (query) Typestring Requiredyes Default— DescriptionPeriod end, YYYY-MM-DD.
Parameterlevel (query) Typestring Requiredno Defaultcampaign DescriptionLevel: campaign, group, or keyword.
ParameterparentId (query) Typeinteger Requiredno Default— DescriptionParent node ID from data.items[].id of this method.
Parametercursor (query) Typestring Requiredno Default— DescriptionContinuation object encoded as JSON. Omit it on the first request.
Parametercursor.field Typestring Requiredyes, in cursor Defaultid DescriptionOnly id.
Parametercursor.value Typestring Requiredyes, in cursor Default— DescriptionNonempty data.cursor.value from the previous page, up to 4096 bytes.
Parametercursor.limit Typeinteger Requiredno Default50 DescriptionPage size from 1 to 100.
Parametercursor.order Typestring Requiredno DefaultASC DescriptionOnly ASC.

When data.hasMore is true, pass the returned data.cursor to the next request with the same dates, level, and parent node. The API does not fetch subsequent pages automatically. The offset parameter is not supported.

Examples

curl — personal key

Terminal 
curl --get "https://vibecode.bitrix24.com/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 application

Terminal 
curl --get "https://vibecode.bitrix24.com/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 — personal key

javascript 
const query = new URLSearchParams({ dateFrom: '2026-10-01', dateTo: '2026-10-07' })
const res = await fetch(`https://vibecode.bitrix24.com/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 application

javascript 
const query = new URLSearchParams({ dateFrom: '2026-10-01', dateTo: '2026-10-07' })
const res = await fetch(`https://vibecode.bitrix24.com/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)

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue
Fielddata Typeobject DescriptionAdvertising tree page.
Fielddata.items Typeobject[] DescriptionNodes at the requested level.
Fielddata.hasMore Typeboolean DescriptionWhether another page exists.
Fielddata.cursor Typeobject DescriptionContinuation cursor.
Fielddata.cursor.field Typestring Descriptionid
Fielddata.cursor.value Typestring or null DescriptionValue for the next request. null at the end of the list.
Fielddata.items[].id Typeinteger DescriptionNode ID. Use as parentId when reading the next level.
Fielddata.items[].code Typestring DescriptionNode code.
Fielddata.items[].enabled Typeboolean DescriptionWhether the node is enabled.
Fielddata.items[].title Typestring DescriptionNode title.
Fielddata.items[].level Typeinteger DescriptionNumeric node level.
Fielddata.items[].nextLevel Typeinteger or null DescriptionNext level number or null.
Fielddata.items[].prevLevel Typeinteger or null DescriptionPrevious level number or null.
Fielddata.items[].impressions Typeinteger DescriptionImpression count.
Fielddata.items[].actions Typeinteger DescriptionAction count.
Fielddata.items[].outcome Typeinteger DescriptionAdvertising outcome metric.
Fielddata.items[].currencyId Typestring DescriptionCurrency code for monetary metrics.
Fielddata.items[].leads Typeinteger DescriptionLead count.
Fielddata.items[].deals Typeinteger DescriptionDeal count.
Fielddata.items[].successDeals Typeinteger DescriptionWon deal count.
Fielddata.items[].cost Typenumber DescriptionCost.
Fielddata.items[].income Typenumber DescriptionIncome.
Fielddata.items[].roi Typenumber DescriptionReturn on investment.
Fielddata.items[].roiScale Typeinteger DescriptionScale of the roi metric.
Fielddata.items[].ctr Typenumber DescriptionClick-through rate.
Fielddata.items[].cpc Typenumber DescriptionCost per click.

Response example

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

Error response example

404 — source not found:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Record with ID = `0` not found"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionInvalid source ID or field type. A tree cursor must be a JSON object.
HTTP400 CodeBITRIX_REST_V3_EXCEPTION_VALIDATION_REQUESTVALIDATIONEXCEPTION DescriptionMissing or invalid dates, or other parameters rejected by Bitrix24. This includes an invalid level or cursor.
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionUnknown query parameter.
HTTP400 CodeCRM_TRACKING_AD_PROVIDER_UNSUPPORTED DescriptionThe source does not support the advertising operation.
HTTP404 CodeENTITY_NOT_FOUND DescriptionSource not found.
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the crm scope.
HTTP403 CodeBITRIX_REST_V3_EXCEPTION_ACCESSDENIEDEXCEPTION DescriptionInsufficient permissions on the Bitrix24 portal.
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no configured Bitrix24 access.
HTTP422 CodeMETHOD_NOT_YET_AVAILABLE DescriptionThe flag is off or the method is not enabled on the portal. error.release is crm 26.2100.0.
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 returned an invalid response structure.

Other Bitrix24 refusal codes, statuses, and messages are preserved. For common API errors, see Errors.

See also