> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Insights

> Отримання щоденної аналітики Facebook Ads у реальному часі за кампанією, групою оголошень або оголошенням

export const PlansAvailable = ({plans = [], maxPackRequired}) => {
  let displayPlans = plans;
  if (plans && plans.length === 1) {
    const lowerCasePlan = plans[0].toLowerCase();
    if (lowerCasePlan === "business") {
      displayPlans = ["Launch", "Business", "Enterprise"];
    } else if (lowerCasePlan === "premium") {
      displayPlans = ["Premium", "Launch", "Business", "Enterprise"];
    }
  }
  return <Note>
Available on {displayPlans.length === 1 ? "the " : ""}
{displayPlans.join(", ").replace(/\b\w/g, l => l.toUpperCase())}{" "}
{displayPlans.length > 1 ? "plans" : "plan"}.

{maxPackRequired && <span onClick={() => window.open('https://www.ayrshare.com/docs/additional/maxpack', '_self')} className="flex items-center mt-2 cursor-pointer">
 <span className="px-1.5 py-0.5 rounded text-sm" style={{
    backgroundColor: '#C264B6',
    color: 'white',
    fontSize: '12px'
  }}>
   Max Pack required
 </span>
</span>}
</Note>;
};

export const HeaderAPI = ({noProfileKey, profileKeyRequired}) => <>
    <ParamField header="Authorization" type="string" required>
      <a href="/docs/apis/overview#authorization">API Key</a> of the Primary Profile.
      <br />
      <br />
      Format: <code>Authorization: Bearer API_KEY</code>
    </ParamField>
    {!noProfileKey && (profileKeyRequired ? <ParamField header="Profile-Key" type="string" required>
          <a href="/docs/apis/overview#profile-key-format">Profile Key</a> of a User Profile.
          <br />
          <br />
          Format: <code>Profile-Key: PROFILE_KEY</code>
        </ParamField> : <ParamField header="Profile-Key" type="string">
          <a href="/docs/apis/overview#profile-key-format">Profile Key</a> of a User Profile.
          <br />
          <br />
          Format: <code>Profile-Key: PROFILE_KEY</code>
        </ParamField>)}
  </>;

<PlansAvailable plans={["premium"]} maxPackRequired={false} />

Отримуйте актуальні показники ефективності оголошень Facebook, по одному рядку на день, для ваших кампаній, груп оголошень або оголошень.
Виберіть потрібні метрики, розбийте їх за віком, статтю, країною або місцем розміщення та переглядайте довгі діапазони дат посторінково.

<ul className="custom-bullets">
  <li>Дані зчитуються з Meta в момент вашого запиту, а не з нічної копії.</li>

  <li>
    Використовуйте [History](/docs/apis/ads/facebook/get-ad-history) для витрат, за які ми виставляємо рахунок. Використовуйте Insights для звітності
    та аналізу.
  </li>

  <li>Усі грошові значення подаються у валюті рекламного облікового запису, яка повертається в `currency` у кожному рядку.</li>

  <li>
    Кампанії мають бути створені через Ayrshare для цього профілю, а групи оголошень мають бути в такій
    кампанії. Оголошення, створене через
    Ayrshare для іншого профілю, буде відхилено. Інші ID оголошень зчитуються через пов'язаний обліковий запис Meta
    цього профілю, тому Meta повертає лише ті оголошення, які бачить цей обліковий запис.
  </li>

  <li>
    Один запит охоплює один рекламний обліковий запис. ID з кількох рекламних облікових записів повертають код `101`, так само як і
    кілька ID оголошень, про які Ayrshare не має записів. Запитуйте їх по одному.
  </li>
</ul>

## Параметри заголовка

<HeaderAPI />

## Параметри запиту

<ParamField query="level" type="string" required>
  Про що звітує кожен рядок: `campaign`, `adSet` або `ad`.
</ParamField>

<ParamField query="ids" type="string">
  ID кампаній, груп оголошень або оголошень через кому, до 50. Обов'язковий для `level=campaign` і
  `level=adSet`.

  З `level=ad` можна не передавати `ids`, а натомість надіслати `accountId`. Тоді звіт охоплює оголошення,
  які ви створили через Ayrshare для цього профілю в цьому рекламному обліковому записі, а не всі оголошення в ньому. Це працює
  для до 50 таких оголошень. Якщо їх більше, надішліть їхні ID або формуйте звіт за кампаніями. Якщо нічого не знайдено,
  звіт буде порожнім.
</ParamField>

<ParamField query="accountId" type="string">
  ID рекламного облікового запису, з префіксом `act_` або без нього (`1234567890` або `act_1234567890`).

  Обов'язковий з `level=ad`, якщо `ids` не передано.
</ParamField>

<ParamField query="metrics" type="string">
  Метрики для повернення через кому. Не передавайте цей параметр, щоб отримати всі. Див. [Метрики](#metrics).
</ParamField>

<ParamField query="breakdowns" type="string">
  Розбивки через кому: `age`, `gender`, `country`, `placement`. Тоді кожен день має один рядок на кожне
  значення або на кожну комбінацію у випадку `age,gender`. Надсилайте одну розбивку за раз або `age,gender`; Meta
  відхиляє інші комбінації (наприклад, `age,country`), тому вони повертають код `101`.
</ParamField>

<ParamField query="startDate" type="string" default="30 днів тому">
  Перший день у форматі `YYYY-MM-DD`. Може бути не раніше ніж 37 місяців тому.
</ParamField>

<ParamField query="endDate" type="string" default="сьогодні">
  Останній день у форматі `YYYY-MM-DD`.
</ParamField>

<ParamField query="cursor" type="string">
  `nextCursor` з попередньої відповіді, щоб отримати наступну сторінку.
</ParamField>

<h2 id="metrics">
  Метрики
</h2>

| Метрика | Тип | Значення |
| - | - | - |
| `spend` | number | Витрачена сума |
| `impressions` | number | Скільки разів оголошення було показано |
| `reach` | number | Люди, які бачили оголошення принаймні один раз |
| `clicks` | number | Кліки |
| `cpm` | number або `null` | Вартість за 1 000 показів |
| `cpc` | number або `null` | Вартість за клік. `null` у день без кліків |
| `ctr` | number або `null` | Показник клікабельності, у відсотках |
| `actions` | array | Кожен тип дії, врахований Meta, з його кількістю |
| `conversionValue` | number | Загальна вартість покупок |

Facebook звітує про кожну метрику з цієї таблиці. Один виняток: Meta не звітує про `reach` для звіту з
`breakdowns`, що починається понад 13 місяців тому, тому `reach` не включається в ці рядки. У мережах, які не звітують про певну метрику, її
не включають у рядки, а не повертають як `0`, а запит такої метрики повертає код `101`.

<Note>
  Meta враховує деякі дії в кількох типах, тому не додавайте значення `actions` між собою. Наприклад,
  `omni_purchase` уже включає `purchase`. `conversionValue` враховує кожну покупку один раз.
</Note>

<h2 id="paging">
  Пагінація
</h2>

Кожна відповідь повертає до 500 рядків. Якщо їх більше, встановлюється `nextCursor`. Надішліть той самий запит
ще раз із `cursor`, що дорівнює цьому значенню, щоб отримати наступну сторінку. На останній сторінці `nextCursor` дорівнює `null`.

<h2 id="errors">
  Помилки
</h2>

| Код | Коли |
| - | - |
| `101` | Параметр відсутній або неправильний, розбивка чи метрика не підтримується, `startDate` більш ніж 37 місяців тому, надіслано понад 50 ID, ID належать до кількох рекламних облікових записів або Meta відхиляє комбінацію розбивок |
| `400` | Кампанія, група оголошень чи оголошення не належить вам, або `accountId` не є рекламним обліковим записом, який Ayrshare має в записах для надісланих ID. Для групи оголошень `accountId` також має бути рекламним обліковим записом, який Meta вказує для неї. Для оголошення без запису в Ayrshare `accountId` не перевіряється, і оголошення зчитується окремо |
| `370` | Meta не змогла повернути аналітику. Спробуйте ще раз |

<RequestExample>
  ```bash cURL theme={"system"}
  curl \
  -H "Authorization: Bearer API_KEY" \
  -X GET "https://api.ayrshare.com/api/ads/facebook/insights?level=campaign&ids=120200000000000001&startDate=2026-09-01&endDate=2026-09-02"
  ```

  ```javascript JavaScript theme={"system"}
  const API_KEY = "API_KEY";
  const params = new URLSearchParams({
    level: "campaign",
    ids: "120200000000000001",
    startDate: "2026-09-01",
    endDate: "2026-09-02",
  });

  fetch(`https://api.ayrshare.com/api/ads/facebook/insights?${params}`, {
    method: "GET",
    headers: { Authorization: `Bearer ${API_KEY}` },
  })
    .then((res) => res.json())
    .then((json) => console.log(json))
    .catch(console.error);
  ```

  ```python Python theme={"system"}
  import requests

  headers = {'Authorization': 'Bearer API_KEY'}
  params = {
      'level': 'campaign',
      'ids': '120200000000000001',
      'startDate': '2026-09-01',
      'endDate': '2026-09-02',
  }

  r = requests.get('https://api.ayrshare.com/api/ads/facebook/insights', headers=headers, params=params)

  print(r.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 200: Success theme={"system"}
  {
    "status": "success",
    "platform": "facebook",
    "level": "campaign",
    "startDate": "2026-09-01",
    "endDate": "2026-09-02",
    "insights": [
      {
        "date": "2026-09-01",
        "level": "campaign",
        "id": "120200000000000001",
        "currency": "USD",
        "spend": 12.34,
        "impressions": 4000,
        "reach": 3100,
        "clicks": 80,
        "cpm": 3.085,
        "cpc": 0.15425,
        "ctr": 2,
        "actions": [
          { "type": "link_click", "value": 75 },
          { "type": "omni_purchase", "value": 3 }
        ],
        "conversionValue": 89.97
      }
    ],
    "count": 1,
    "nextCursor": null
  }
  ```

  ```json 200: Breakdowns theme={"system"}
  {
    "status": "success",
    "platform": "facebook",
    "level": "ad",
    "startDate": "2026-09-01",
    "endDate": "2026-09-01",
    "insights": [
      {
        "date": "2026-09-01",
        "level": "ad",
        "id": "120210000000000001",
        "age": "25-34",
        "gender": "female",
        "currency": "EUR",
        "spend": 1.5,
        "impressions": 300
      },
      {
        "date": "2026-09-01",
        "level": "ad",
        "id": "120210000000000001",
        "age": "25-34",
        "gender": "male",
        "currency": "EUR",
        "spend": 1,
        "impressions": 200
      }
    ],
    "count": 2,
    "nextCursor": null
  }
  ```

  ```json 400: Not Yours theme={"system"}
  {
    "action": "ads",
    "status": "error",
    "code": 400,
    "message": "The ad is not found or not authorized."
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.