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

> Live-Tagesdaten zu Instagram-Anzeigen nach Kampagne oder Anzeige abrufen

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

Rufen Sie die Live-Leistung Ihrer Instagram-Anzeigen ab, eine Zeile pro Tag, für Ihre Kampagnen oder Anzeigen.
Wählen Sie die gewünschten Kennzahlen, schlüsseln Sie sie nach Alter, Geschlecht, Land oder Platzierung auf und blättern Sie seitenweise durch lange Zeiträume.

<ul className="custom-bullets">
  <li>Die Zahlen werden beim Aufruf direkt von Meta gelesen, nicht aus einer nächtlichen Kopie.</li>

  <li>
    Verwenden Sie [Verlauf](/docs/apis/ads/instagram/get-ad-history) für die Ausgaben, die wir abrechnen. Verwenden Sie Insights für Reporting
    und Analysen.
  </li>

  <li>Alle Geldwerte sind in der Währung des Werbekontos angegeben, die in jeder Zeile in `currency` zurückgegeben wird.</li>

  <li>
    Kampagnen müssen über Ayrshare für dieses Profil erstellt worden sein. Eine Anzeige, die über
    Ayrshare für ein anderes Profil erstellt wurde, wird abgelehnt. Andere Anzeigen-IDs werden mit dem verknüpften Meta-Konto
    dieses Profils gelesen, sodass Meta nur Anzeigen zurückgibt, die dieses Konto sehen kann.
  </li>

  <li>
    Eine Anfrage umfasst ein Werbekonto. IDs aus mehreren Werbekonten geben den Code `101` zurück, ebenso
    mehrere Anzeigen-IDs, zu denen Ayrshare keinen Eintrag hat. Fragen Sie diese einzeln ab.
  </li>
</ul>

## Header-Parameter

<HeaderAPI />

## Query-Parameter

<ParamField query="level" type="string" required>
  Worauf sich jede Zeile bezieht: `campaign` oder `ad`.

  `adSet` wird noch nicht unterstützt und gibt den Code `101` zurück.
</ParamField>

<ParamField query="ids" type="string">
  Kommagetrennte Kampagnen- oder Anzeigen-IDs, bis zu 50. Erforderlich für `level=campaign`.

  Mit `level=ad` können Sie `ids` weglassen und stattdessen `accountId` senden. Dann wird über die Anzeigen
  berichtet, die Sie über Ayrshare für dieses Profil in diesem Werbekonto erstellt haben, nicht über alle Anzeigen darin. Das funktioniert
  für bis zu 50 solcher Anzeigen. Für mehr senden Sie deren IDs oder berichten nach Kampagne. Werden keine gefunden, ist der
  Bericht leer.
</ParamField>

<ParamField query="accountId" type="string">
  Die ID des Werbekontos, mit oder ohne das Präfix `act_` (`1234567890` oder `act_1234567890`).

  Erforderlich mit `level=ad`, wenn `ids` weggelassen wird.
</ParamField>

<ParamField query="metrics" type="string">
  Kommagetrennte Kennzahlen, die zurückgegeben werden sollen. Lassen Sie den Parameter weg, um alle zu erhalten. Siehe [Kennzahlen](#metrics).
</ParamField>

<ParamField query="breakdowns" type="string">
  Kommagetrennte Aufschlüsselungen: `age`, `gender`, `country`, `placement`. Jeder Tag hat dann eine Zeile pro
  Wert bzw. pro Kombination bei `age,gender`. Senden Sie jeweils eine Aufschlüsselung oder `age,gender`; Meta
  lehnt andere Kombinationen (wie `age,country`) ab, daher geben sie den Code `101` zurück.
</ParamField>

<ParamField query="startDate" type="string" default="vor 30 Tagen">
  Erster Tag im Format `YYYY-MM-DD`. Er kann bis zu 37 Monate zurückliegen.
</ParamField>

<ParamField query="endDate" type="string" default="heute">
  Letzter Tag im Format `YYYY-MM-DD`.
</ParamField>

<ParamField query="cursor" type="string">
  Der `nextCursor` aus der vorherigen Antwort, um die nächste Seite abzurufen.
</ParamField>

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

| Kennzahl | Typ | Bedeutung |
| - | - | - |
| `spend` | number | Ausgegebener Betrag |
| `impressions` | number | Wie oft die Anzeige ausgespielt wurde |
| `reach` | number | Personen, die die Anzeige mindestens einmal gesehen haben |
| `clicks` | number | Klicks |
| `cpm` | number oder `null` | Kosten pro 1.000 Impressionen |
| `cpc` | number oder `null` | Kosten pro Klick. `null` an einem Tag ohne Klicks |
| `ctr` | number oder `null` | Klickrate in Prozent |
| `actions` | array | Jeder von Meta gezählte Aktionstyp mit seiner Anzahl |
| `conversionValue` | number | Gesamtwert der Käufe |

Instagram liefert jede Kennzahl in dieser Tabelle. Eine Ausnahme: Meta liefert `reach` nicht für einen Bericht mit
`breakdowns`, der mehr als 13 Monate zurückliegend beginnt, daher fehlt `reach` in diesen Zeilen. Bei Netzwerken, die eine Kennzahl nicht liefern, fehlt sie
in den Zeilen, statt als `0` zurückgegeben zu werden, und eine Anfrage danach gibt den Code `101` zurück.

<Note>
  Meta zählt manche Aktionen unter mehr als einem Typ, addieren Sie die Werte von `actions` daher nicht. Zum
  Beispiel enthält `omni_purchase` bereits `purchase`. `conversionValue` zählt jeden Kauf einmal.
</Note>

## Paginierung

Jede Antwort liefert bis zu 500 Zeilen. Gibt es mehr, ist `nextCursor` gesetzt. Senden Sie dieselbe Anfrage
erneut mit `cursor` auf diesen Wert gesetzt, um die nächste Seite abzurufen. Auf der letzten Seite ist `nextCursor` `null`.

## Fehler

| Code | Wann |
| - | - |
| `101` | Ein Parameter fehlt oder ist falsch, eine Aufschlüsselung oder Kennzahl wird nicht unterstützt, `level=adSet` wird gesendet, `startDate` liegt mehr als 37 Monate zurück, mehr als 50 IDs werden gesendet, die IDs gehören zu mehr als einem Werbekonto oder Meta lehnt die Kombination der Aufschlüsselungen ab |
| `400` | Eine Kampagne oder Anzeige gehört nicht Ihnen, oder `accountId` ist nicht das Werbekonto, das Ayrshare für die gesendeten IDs gespeichert hat. Bei einer Anzeige ohne Ayrshare-Eintrag wird `accountId` nicht geprüft und die Anzeige wird für sich allein gelesen |
| `370` | Meta konnte die Insights nicht zurückgeben. Versuchen Sie es erneut |

<RequestExample>
  ```bash cURL theme={"system"}
  curl \
  -H "Authorization: Bearer API_KEY" \
  -X GET "https://api.ayrshare.com/api/ads/instagram/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/instagram/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/instagram/insights', headers=headers, params=params)

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

<ResponseExample>
  ```json 200: Success theme={"system"}
  {
    "status": "success",
    "platform": "instagram",
    "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": "instagram",
    "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.