> ## 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

> Obtenir en direct les insights publicitaires Facebook quotidiens par campagne ou par annonce

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} />

Obtenez en direct les performances de vos annonces Facebook, une ligne par jour, pour vos campagnes ou vos annonces.
Choisissez les indicateurs souhaités, ventilez-les par âge, genre, pays ou placement, et parcourez de longues périodes page par page.

<ul className="custom-bullets">
  <li>Les chiffres sont lus auprès de Meta au moment de votre appel, et non à partir d'une copie nocturne.</li>

  <li>
    Utilisez [Historique](/docs/apis/ads/facebook/get-ad-history) pour les dépenses que nous facturons. Utilisez Insights pour le reporting
    et l'analyse.
  </li>

  <li>Toutes les valeurs monétaires sont exprimées dans la devise du compte publicitaire, renvoyée dans `currency` sur chaque ligne.</li>

  <li>
    Les campagnes doivent avoir été créées via Ayrshare pour ce profil. Une annonce créée via
    Ayrshare pour un autre profil est refusée. Les autres ID d'annonce sont lus avec le compte Meta
    lié à ce profil, Meta ne renvoie donc que les annonces visibles par ce compte.
  </li>

  <li>
    Une requête porte sur un seul compte publicitaire. Des ID provenant de plusieurs comptes publicitaires renvoient le code `101`, tout comme
    plusieurs ID d'annonce dont Ayrshare n'a aucune trace. Demandez-les un par un.
  </li>
</ul>

## Paramètres d'en-tête

<HeaderAPI />

## Paramètres de requête

<ParamField query="level" type="string" required>
  Ce sur quoi porte chaque ligne : `campaign` ou `ad`.

  `adSet` n'est pas encore pris en charge et renvoie le code `101`.
</ParamField>

<ParamField query="ids" type="string">
  ID de campagnes ou d'annonces séparés par des virgules, jusqu'à 50. Obligatoire pour `level=campaign`.

  Avec `level=ad`, vous pouvez omettre `ids` et envoyer `accountId` à la place. Le rapport porte alors sur les annonces
  que vous avez créées via Ayrshare pour ce profil dans ce compte publicitaire, et non sur toutes ses annonces. Cela fonctionne
  jusqu'à 50 annonces de ce type. Au-delà, envoyez leurs ID ou établissez le rapport par campagne. Si aucune n'est trouvée, le
  rapport est vide.
</ParamField>

<ParamField query="accountId" type="string">
  L'ID du compte publicitaire, avec ou sans le préfixe `act_` (`1234567890` ou `act_1234567890`).

  Obligatoire avec `level=ad` lorsque `ids` est omis.
</ParamField>

<ParamField query="metrics" type="string">
  Indicateurs à renvoyer, séparés par des virgules. Omettez-le pour les obtenir tous. Consultez [Indicateurs](#metrics).
</ParamField>

<ParamField query="breakdowns" type="string">
  Ventilations séparées par des virgules : `age`, `gender`, `country`, `placement`. Chaque jour comporte alors une ligne par
  valeur, ou par combinaison avec `age,gender`. Envoyez une ventilation à la fois, ou `age,gender` ; Meta
  refuse les autres combinaisons (comme `age,country`), qui renvoient donc le code `101`.
</ParamField>

<ParamField query="startDate" type="string" default="il y a 30 jours">
  Premier jour, au format `YYYY-MM-DD`. Il peut remonter jusqu'à 37 mois.
</ParamField>

<ParamField query="endDate" type="string" default="aujourd'hui">
  Dernier jour, au format `YYYY-MM-DD`.
</ParamField>

<ParamField query="cursor" type="string">
  Le `nextCursor` de la réponse précédente, pour obtenir la page suivante.
</ParamField>

<h2 id="metrics">
  Indicateurs
</h2>

| Indicateur | Type | Signification |
| - | - | - |
| `spend` | nombre | Montant dépensé |
| `impressions` | nombre | Nombre de fois où l'annonce a été affichée |
| `reach` | nombre | Personnes ayant vu l'annonce au moins une fois |
| `clicks` | nombre | Clics |
| `cpm` | nombre ou `null` | Coût pour 1 000 impressions |
| `cpc` | nombre ou `null` | Coût par clic. `null` un jour sans clic |
| `ctr` | nombre ou `null` | Taux de clics, en pourcentage |
| `actions` | tableau | Chaque type d'action comptabilisé par Meta, avec son nombre |
| `conversionValue` | nombre | Valeur totale des achats |

Facebook fournit tous les indicateurs de ce tableau. Une exception : Meta ne fournit pas `reach` pour un rapport avec
`breakdowns` qui commence il y a plus de 13 mois, donc `reach` est omis de ces lignes. Sur les réseaux qui ne fournissent pas un indicateur, celui-ci est omis
des lignes au lieu d'être renvoyé avec la valeur `0`, et le demander renvoie le code `101`.

<Note>
  Meta comptabilise certaines actions sous plusieurs types, n'additionnez donc pas les valeurs de `actions`. Par
  exemple, `omni_purchase` inclut déjà `purchase`. `conversionValue` compte chaque achat une seule fois.
</Note>

## Pagination

Chaque réponse renvoie jusqu'à 500 lignes. S'il y en a davantage, `nextCursor` est renseigné. Renvoyez la même requête
avec `cursor` défini sur cette valeur pour obtenir la page suivante. Sur la dernière page, `nextCursor` vaut `null`.

## Erreurs

| Code | Quand |
| - | - |
| `101` | Un paramètre est manquant ou incorrect, une ventilation ou un indicateur n'est pas pris en charge, `level=adSet` est envoyé, `startDate` remonte à plus de 37 mois, plus de 50 ID sont envoyés, les ID appartiennent à plusieurs comptes publicitaires, ou Meta refuse la combinaison de ventilations |
| `400` | Une campagne ou une annonce ne vous appartient pas, ou `accountId` n'est pas le compte publicitaire enregistré par Ayrshare pour les ID envoyés. Pour une annonce sans enregistrement Ayrshare, `accountId` n'est pas vérifié et l'annonce est lue seule |
| `370` | Meta n'a pas pu renvoyer les insights. Réessayez |

<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.