Ads Insights API

Ads Insights API предоставляет данные и статистику результативности рекламы на платформах Meta. Благодаря гибким возможностям создания отчетов вы можете настраивать запросы и получать информацию практически по всем метрикам, доступным в Meta Ads Manager.

Прежде чем начать

Для доступа к Ads Insights API вам потребуются:

приложение (подробнее см. в статье Разработка приложений Meta);
разрешение ads_read (подробнее см. в статьях Разрешения и Получение разрешения).

Вы также должны настроить свои объявления, чтобы отслеживать интересующие вас действия. Для этого можно использовать такие инструменты, как Conversions API или "Пиксель Meta".

Вызов Ads Insights API

Ads Insights API доступен как граница контекста для любого объекта рекламы. (Подробнее об иерархии рекламы Meta см. здесь.)

Ресурс	Что предоставляет?
`/{ad-account-id}/insights`	Статистика рекламного аккаунта
`/{campaign-id}/insights`	Статистика рекламной кампании
`/{ad-set-id}/insights`	Статистика группы объявлений
`/{ad-id}/insights`	Статистика объявления

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

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

curl -G \ -d "access_token=<ACCESS_TOKEN>" \ "https://graph.facebook.com/v26.0/<CAMPAIGN_ID>/insights"

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

{
  "data": [
    {
      "account_id": "<AD_ACCOUNT_ID>",
      "campaign_id": "<CAMPAIGN_ID>",
      "date_start": "2025-03-14",
      "date_stop": "2025-04-12",
      "impressions": "361324",
      "spend": "5339.5"
    }
  ],
  "paging": {
    "cursors": {
    "before": "MAZDZD",
    "after": "MAZDZD"
    }
  }
}

Настройка запросов

Вы можете получить гораздо более конкретные данные, используя в запросе три основных компонента: параметры (для указания временных диапазонов, окон атрибуции и т. д.), поля (т. е. метрики) и разбивки. Например, чтобы узнать количество кликов (все) с разбивкой по полу за последние 7 дней вашей кампании, вы можете включить в запрос:

Параметры: date_preset=last_7d
Поля: clicks
Разбивки: gender

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

curl -G \ -d "date_preset=last_7d" \ -d "fields=clicks" \ -d "breakdowns=gender" \ -d "access_token=<ACCESS_TOKEN>" \ "https://graph.facebook.com/v26.0/<CAMPAIGN_ID>/insights"

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

{
  "data": [
    {
      "clicks": "7346",
      "date_start": "2025-04-06",
      "date_stop": "2025-04-12",
      "gender": "female"
    },
    {
      "clicks": "3788",
      "date_start": "2025-04-06",
      "date_stop": "2025-04-12",
      "gender": "male"
    },
    {
      "clicks": "79",
      "date_start": "2025-04-06",
      "date_stop": "2025-04-12",
      "gender": "unknown"
    },
  ],
  "paging": {
    "cursors": {
    "before": "MAZDZD",
    "after": "MAZDZD"
    }
  }
}

Дополнительная информация

Ads Insights API — мощный и эффективный инструмент. Ознакомьтесь с дополнительными материалами, чтобы узнать больше о его функциях:

Параметры и поля
Метрики
Разбивки
Асинхронные запросы
Ограничения и рекомендации
Руководства по отчетности по конверсиям, отчетности на уровне продукта и моделированию маркетинг-микса

Кроме того, для каждой границы контекста статистики рекламного объекта есть автоматически сгенерированная справочная документация:

Если вы планируете включить в свое решение данные из Ads Insights API, ознакомьтесь также с Условиями платформы Meta и Правилами для разработчиков для Marketing API.