---
slug: "vk-ads"
name: "API VK Рекламы"
vendor: "VK"
industry: "marketing"
docsUrl: "https://ads.vk.ru/en/doc/api/info/Authorization"
version: 2
updatedAt: "2026-10-24"
---

# API VK Рекламы

Отрасль: Реклама и аналитика. Актуально на 2026-10-24.

API рекламной платформы VK Реклама: получение токенов доступа (для своего кабинета, агентских и менеджерских клиентов), управление кампаниями и группами объявлений, список объявлений и статистика по объявлениям, кампаниям и пользователям. Ответы — JSON; списки возвращаются с полями `count`, `offset`, `items`.

## Сценарии

### Получить токен доступа к рекламному кабинету

Первый шаг интеграции: токен для своего кабинета или для клиентов агентства.

1. Получи client_id и client_secret доступа к API в кабинете VK Рекламы.
2. Запроси токен для своего кабинета: POST /api/v2/oauth2/token.json с grant_type = client_credentials, client_id и client_secret (form-urlencoded). Для клиента агентства — grant_type = agency_client_credentials и agency_client_name или agency_client_id.
3. Токен живёт сутки (expires_in = 86400). Продлевай его тем же методом с grant_type = refresh_token, а не запрашивай новый: на пару «client_id + пользователь» — не больше 5 токенов одновременно, сверх лимита придёт 403.
4. Передавай токен в заголовке Authorization: Bearer <access_token>.

```bash
curl -X POST https://ads.vk.ru/api/v2/oauth2/token.json \
  -d grant_type=client_credentials -d client_id=<client_id> -d client_secret=<client_secret>

# Продление
curl -X POST https://ads.vk.ru/api/v2/oauth2/token.json \
  -d grant_type=refresh_token -d refresh_token=<refresh_token> -d client_id=<client_id> -d client_secret=<client_secret>
```

### Выгрузить статистику кампаний по дням

Показы, клики и расходы по кампаниям — в отчёт или сквозную аналитику.

1. Получи кампании: GET /api/v2/ad_plans.json с limit и offset; только активные — _status = active.
2. Запроси статистику: GET /api/v2/statistics/{object}/{period}.json с object = campaigns, period = day, id — ID кампаний через запятую (до 200), date_from и date_to. Набор метрик — metrics (base по умолчанию, all — всё).
3. В ответе items[] с rows по датам и total. Посуточная статистика доступна за последние 365 дней.
4. Для больших выборок с сортировкой и постраничным выводом используй GET /api/v3/statistics/{object}/day.json с limit (до 250) и offset.

```bash
curl -G "https://ads.vk.ru/api/v2/statistics/campaigns/day.json" \
  -H "Authorization: Bearer $VKADS_TOKEN" \
  -d id=6617841,6711647 -d date_from=2026-10-01 -d date_to=2026-10-23 -d metrics=base
```

### Создать кампанию с группой объявлений

Запускать типовые кампании из своей системы: под новый товар, город или акцию.

1. Создай кампанию: POST /api/v2/ad_plans.json с name, objective (цель), date_start, date_end, бюджетами budget_limit_day и budget_limit и autobidding_mode. Без status кампания будет активной — передай status, если её нельзя запускать сразу.
2. Группы объявлений можно передать сразу в ad_groups или создать отдельно: POST /api/v2/ad_groups.json с name, package_id (формат размещения), targetings и banners.
3. Ответ 400 — ошибка валидации, подробности в теле. Проверь созданное: GET /api/v2/ad_groups.json и GET /api/v2/banners.json с фильтром _campaign_id.

```bash
curl -X POST https://ads.vk.ru/api/v2/ad_plans.json \
  -H "Authorization: Bearer $VKADS_TOKEN" -H 'Content-Type: application/json' \
  -d '{
        "name": "Кружки — осень 2026",
        "status": "blocked",
        "date_start": "2026-11-01 00:00:00",
        "date_end": "2026-11-30 00:00:00",
        "autobidding_mode": "max_goals",
        "budget_limit_day": "1000",
        "budget_limit": "20000",
        "objective": "<цель кампании>",
        "ad_groups": []
      }'
```

## Базовые URL

- Боевой: `https://ads.vk.ru`
- Методы: `/api/v2/`

## Авторизация

Тип: OAuth 2.0

Токен получают методом `POST /api/v2/oauth2/token.json` (`application/x-www-form-urlencoded`) и передают в заголовке:

Токен живёт сутки (`expires_in` = 86400) и продлевается через `refresh_token`. На пару «client_id + пользователь» — не больше 5 токенов одновременно; запрос сверх лимита возвращает HTTP 403.

```
Authorization: Bearer {access_token}
```

## Методы

### POST /api/v2/oauth2/token.json — Получение токена

В ответе: `access_token`, `token_type`, `scope`, `expires_in`, `refresh_token`.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `grant_type` | body | string | да | client_credentials, agency_client_credentials, authorization_code или refresh_token |
| `client_id` | body | string | да | ID клиента API |
| `client_secret` | body | string | нет | Секрет; нужен для client_credentials, agency_client_credentials, refresh_token |
| `agency_client_name` | body | string | нет | Клиент агентства/менеджера (или agency_client_id) |
| `agency_client_id` | body | string | нет | ID клиента агентства/менеджера |
| `code` | body | string | нет | Код из редиректа для authorization_code |
| `refresh_token` | body | string | нет | Refresh-токен для продления |

### GET /api/v2/ad_plans.json — Список кампаний

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `limit` | query | integer | нет | Число кампаний, по умолчанию 20 |
| `offset` | query | integer | нет | Смещение |
| `_id` | query | integer | нет | Фильтр по ID; несколько — _id__in=6617841,6711647 |
| `_status` | query | string | нет | active, blocked, deleted; также _status__ne, _status__in |
| `sorting` | query | string | нет | id, name, status; минус — по убыванию, например -id |

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

```json
{
    "count": 3,
    "offset": 0,
    "items": [
        {
            "id": 6617841,
            "name": "New campaign 2022-07-15 17:53"
        },
        {
            "id": 6711647,
            "name": "New campaign 2022-08-16 19:49"
        },
        {
            "id": 6711665,
            "name": "New campaign 2022-08-16 19:51"
        }
    ]
}
```

### POST /api/v2/ad_plans.json — Создание кампании

Если `status` не передан, ставится `active`. Ответ: `id` (и `ad_groups`, если кампания создана с группами); 400 — ошибка валидации.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `name` | body | string | нет | Название кампании |
| `status` | body | string | нет | Статус, по умолчанию active |
| `date_start` | body | string | нет | Дата начала |
| `date_end` | body | string | нет | Дата окончания |
| `autobidding_mode` | body | string | нет | Стратегия ставок, например max_goals |
| `budget_limit_day` | body | string | нет | Дневной бюджет |
| `budget_limit` | body | string | нет | Общий бюджет |
| `objective` | body | string | нет | Цель кампании |
| `ad_groups` | body | array | нет | Группы объявлений |

Пример запроса:

```
POST /api/v2/ad_plans.json
{
    "name": "My new campaign",
    "status": "active",
    "date_start": "2022-04-01 00:00:00",
    "date_end": "2022-04-15 00:00:00",
    "autobidding_mode": "max_goals",
    "budget_limit_day": "1000",
    "budget_limit": "5000",
    "enable_utm": "False",
    "enable_offline_goals": "False",
    "objective": "playersengagement",
    "ad_groups": []
}
```

### GET /api/v2/ad_groups.json — Список групп объявлений

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `limit` | query | integer | нет | Число групп, по умолчанию 20 |
| `offset` | query | integer | нет | Смещение |
| `_id` | query | integer | нет | Фильтр по ID (_id__in) |
| `_status` | query | string | нет | active, blocked, deleted |
| `_last_updated` | query | string | нет | Дата обновления с __lt, __lte, __gt, __gte |
| `sorting` | query | string | нет | id, name, status |

### POST /api/v2/ad_groups.json — Создание группы объявлений

Ответ: `id` и `banners` (если объявления переданы).

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `name` | body | string | нет | Название группы |
| `status` | body | string | нет | По умолчанию active |
| `date_start` | body | string | нет | Дата начала |
| `date_end` | body | string | нет | Дата окончания |
| `budget_limit_day` | body | string | нет | Дневной бюджет |
| `budget_limit` | body | string | нет | Общий бюджет (кратно budget_limit_step) |
| `package_id` | body | integer | нет | Пакет (формат размещения) |
| `banners` | body | array | нет | Объявления: content, urls, textblocks |
| `targetings` | body | object | нет | Таргетинги: пол, возраст, гео, интересы, pads |

### GET /api/v2/banners.json — Список объявлений

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `limit` | query | integer | нет | По умолчанию 20 |
| `offset` | query | integer | нет | Смещение |
| `_id` | query | integer | нет | Фильтр по ID (_id__in) |
| `_campaign_id` | query | integer | нет | Фильтр по кампании (_campaign_id__in) |
| `_status` | query | string | нет | active, blocked, deleted |
| `_updated` | query | string | нет | Дата обновления с __lt, __lte, __gt, __gte |
| `_url` | query | string | нет | Поиск по URL объявления (с учётом регистра) |
| `_textblock` | query | string | нет | Поиск по тексту объявления (с учётом регистра) |

### GET /api/v2/statistics/{object}/{period}.json — Статистика

`object` — `banners`, `campaigns` или `users`; `period` — `day` или `summary`.

В ответе: `items[]` (`id`, `rows` по датам, `total`) и общий `total`.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `object` | path | string | да | banners, campaigns, users |
| `period` | path | string | да | day или summary |
| `id` | query | string | да | ID объектов через запятую, до 200 |
| `date_from` | query | string | нет | Начало периода YYYY-MM-DD (обязателен для day) |
| `date_to` | query | string | нет | Конец периода включительно (обязателен для day) |
| `metrics` | query | string | нет | all, base (по умолчанию), events, video, uniques, tps, playable, romi |
| `attribution` | query | string | нет | Модель атрибуции impression; для summary игнорируется |

### GET /api/v3/statistics/{object}/day.json — Статистика с пагинацией

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `object` | path | string | да | banners, campaigns, users |
| `date_from` | query | string | да | Начало периода YYYY-MM-DD |
| `date_to` | query | string | нет | Конец периода, по умолчанию текущая дата |
| `id` | query | string | нет | ID объектов через запятую |
| `fields` | query | string | нет | Наборы метрик, по умолчанию base |
| `attribution` | query | string | нет | impression или conversion (по умолчанию) |
| `campaign_id` | query | string | нет | Фильтр по кампаниям (для статистики объявлений) |
| `sort_by` | query | string | нет | Сортировка metric.field_name |
| `d` | query | string | нет | Направление: asc (по умолчанию) или desc |
| `limit` | query | integer | нет | 1–250, по умолчанию 20 |
| `offset` | query | integer | нет | Смещение, по умолчанию 0 |

## Нюансы

- Фильтры в списках задаются префиксом `_` и суффиксами `__in`, `__ne`, `__lt`, `__lte`, `__gt`, `__gte`.
- `ad_groups` нельзя запрашивать через `fields` в списке кампаний.
- Посуточная статистика доступна не больше чем за последние 365 дней.
- Временные токены удаляются автоматически после месяца без использования.
- Есть отдельные эндпоинты статистики по целям (`/api/v2/statistics/goals/...`), in-app событиям (`/api/v2/statistics/inapp/...`) и офлайн-конверсиям.
- Для агентств и менеджеров — ресурсы AgencyClients и ManagerClients и токен с `grant_type=agency_client_credentials`.

## Ошибки

| Код | Описание |
|---|---|
| `400` | Ошибка валидации |
| `403` | Превышен лимит токенов (5 на пару client_id и пользователь) или нет доступа |

## Ограничения

- Не больше 5 токенов одновременно на пару «client_id + пользователь».
- Статистика v2 — до 200 объектов за запрос; v3 — до 250 строк на страницу.

## Источники

- [Авторизация в API](https://ads.vk.ru/en/doc/api/info/Authorization)
- [Кампании (AdPlans)](https://ads.vk.ru/en/doc/api/resource/AdPlans)
- [Группы объявлений (AdGroups)](https://ads.vk.ru/en/doc/api/resource/AdGroups)
- [Объявления (Banners)](https://ads.vk.ru/en/doc/api/resource/Banners)
- [Статистика](https://ads.vk.ru/en/doc/api/info/Statistics)

---

Если этого недостаточно — официальная документация: https://ads.vk.ru/en/doc/api/info/Authorization
JSON: https://mcp-everything.ru/api/integrations/vk-ads. MCP: https://mcp-everything.ru/mcp