> **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 |
|---|---|---|---|---|
| `id` (path) | integer | yes | — | Positive source ID from the [source list](/docs/entities/crm-tracking/sources-list). |
| `dateFrom` (query) | string | yes | — | Period start, `YYYY-MM-DD`. |
| `dateTo` (query) | string | yes | — | Period end, `YYYY-MM-DD`. |
| `level` (query) | string | no | `campaign` | Level: `campaign`, `group`, or `keyword`. |
| `parentId` (query) | integer | no | — | Parent node ID from `data.items[].id` of [this method](/docs/entities/crm-tracking/ad-tree-list). |
| `cursor` (query) | string | no | — | Continuation object encoded as JSON. Omit it on the first request. |
| `cursor.field` | string | yes, in cursor | `id` | Only `id`. |
| `cursor.value` | string | yes, in cursor | — | Nonempty `data.cursor.value` from the previous page, up to 4096 bytes. |
| `cursor.limit` | integer | no | `50` | Page size from 1 to 100. |
| `cursor.order` | string | no | `ASC` | Only `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

```bash
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

```bash
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 |
|---|---|---|
| `success` | boolean | `true` |
| `data` | object | Advertising tree page. |
| `data.items` | object[] | Nodes at the requested level. |
| `data.hasMore` | boolean | Whether another page exists. |
| `data.cursor` | object | Continuation cursor. |
| `data.cursor.field` | string | `id` |
| `data.cursor.value` | string or null | Value for the next request. `null` at the end of the list. |
| `data.items[].id` | integer | Node ID. Use as `parentId` when reading the next level. |
| `data.items[].code` | string | Node code. |
| `data.items[].enabled` | boolean | Whether the node is enabled. |
| `data.items[].title` | string | Node title. |
| `data.items[].level` | integer | Numeric node level. |
| `data.items[].nextLevel` | integer or null | Next level number or `null`. |
| `data.items[].prevLevel` | integer or null | Previous level number or `null`. |
| `data.items[].impressions` | integer | Impression count. |
| `data.items[].actions` | integer | Action count. |
| `data.items[].outcome` | integer | Advertising outcome metric. |
| `data.items[].currencyId` | string | Currency code for monetary metrics. |
| `data.items[].leads` | integer | Lead count. |
| `data.items[].deals` | integer | Deal count. |
| `data.items[].successDeals` | integer | Won deal count. |
| `data.items[].cost` | number | Cost. |
| `data.items[].income` | number | Income. |
| `data.items[].roi` | number | Return on investment. |
| `data.items[].roiScale` | integer | Scale of the `roi` metric. |
| `data.items[].ctr` | number | Click-through rate. |
| `data.items[].cpc` | number | Cost 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 |
|---|---|---|
| 400 | `INVALID_PARAMS` | Invalid source ID or field type. A tree cursor must be a JSON object. |
| 400 | `BITRIX_REST_V3_EXCEPTION_VALIDATION_REQUESTVALIDATIONEXCEPTION` | Missing or invalid dates, or other parameters rejected by Bitrix24. This includes an invalid level or cursor. |
| 400 | `UNKNOWN_FILTER_FIELD` | Unknown query parameter. |
| 400 | `CRM_TRACKING_AD_PROVIDER_UNSUPPORTED` | The source does not support the advertising operation. |
| 404 | `ENTITY_NOT_FOUND` | Source not found. |
| 403 | `SCOPE_DENIED` | The key lacks the `crm` scope. |
| 403 | `BITRIX_REST_V3_EXCEPTION_ACCESSDENIEDEXCEPTION` | Insufficient permissions on the Bitrix24 portal. |
| 401 | `TOKEN_MISSING` | The key has no configured Bitrix24 access. |
| 422 | `METHOD_NOT_YET_AVAILABLE` | The flag is off or the method is not enabled on the portal. `error.release` is `crm 26.2100.0`. |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 returned an invalid response structure. |

Other Bitrix24 refusal codes, statuses, and messages are preserved. For common API errors, see [Errors](/docs/errors).

## See also

- [List analytics sources](/docs/entities/crm-tracking/sources-list)
- [Run a step of the advertising expense report](/docs/entities/crm-tracking/ad-expenses-start)
- [Get advertising expense report progress](/docs/entities/crm-tracking/ad-expenses-get-status)