API VK Рекламы API

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

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

Сценарии

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

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

Получи client_id и client_secret доступа к API в кабинете VK Рекламы.
Запроси токен для своего кабинета: 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.
Токен живёт сутки (expires_in = 86400). Продлевай его тем же методом с grant_type = refresh_token, а не запрашивай новый: на пару «client_id + пользователь» — не больше 5 токенов одновременно, сверх лимита придёт 403.
Передавай токен в заголовке Authorization: Bearer .

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>

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

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

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

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

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

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

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

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

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

{
    "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 строк на страницу.

Источники

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