Insights

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"

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);

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())

{
  "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
}

{
  "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
}

{
  "action": "ads",
  "status": "error",
  "code": 400,
  "message": "The ad is not found or not authorized."
}

GET

ads

facebook

insights

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"

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);

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())

{
  "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
}

{
  "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
}

{
  "action": "ads",
  "status": "error",
  "code": 400,
  "message": "The ad is not found or not authorized."
}

Rufen Sie die Live-Leistung Ihrer Facebook-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.

Die Zahlen werden beim Aufruf direkt von Meta gelesen, nicht aus einer nächtlichen Kopie.
Verwenden Sie Verlauf für die Ausgaben, die wir abrechnen. Verwenden Sie Insights für Reporting und Analysen.
Alle Geldwerte sind in der Währung des Werbekontos angegeben, die in jeder Zeile in currency zurückgegeben wird.
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.
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.

Header-Parameter

Query-Parameter

string

erforderlich

Worauf sich jede Zeile bezieht: campaign oder ad.adSet wird noch nicht unterstützt und gibt den Code 101 zurück.

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.

string

Die ID des Werbekontos, mit oder ohne das Präfix act_ (1234567890 oder act_1234567890).Erforderlich mit level=ad, wenn ids weggelassen wird.

string

Kommagetrennte Kennzahlen, die zurückgegeben werden sollen. Lassen Sie den Parameter weg, um alle zu erhalten. Siehe Kennzahlen.

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.

string

Standard:"vor 30 Tagen"

Erster Tag im Format YYYY-MM-DD. Er kann bis zu 37 Monate zurückliegen.

string

Standard:"heute"

Letzter Tag im Format YYYY-MM-DD.

string

Der nextCursor aus der vorherigen Antwort, um die nächste Seite abzurufen.

Kennzahlen

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

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

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.

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

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"

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);

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())

{
  "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
}

{
  "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
}

{
  "action": "ads",
  "status": "error",
  "code": 400,
  "message": "The ad is not found or not authorized."
}

Get Started

API Endpoints

Multiple Users

Dashboard

Additional

Header-Parameter

Query-Parameter

Kennzahlen

Paginierung

Fehler

​Header-Parameter

​Query-Parameter

​Kennzahlen

​Paginierung

​Fehler

Header-Parameter

Query-Parameter

Kennzahlen

Paginierung

Fehler