AIAI AdBaseChatGPT Ads Guide

Tutorial · Schritt 14 von 14

Insights API für eigene Tracking-App anbinden

OpenAI Ads Insights API nutzen, um Kosten, Impressionen, Klicks und Conversion-Ergebnisse in eigene Dashboards oder Tracking-Apps zu importieren.

Kurzfassung

Die Conversions API sendet Ereignisse an OpenAI. Die Insights API macht das Gegenteil: Sie holt aggregierte Performance-Daten aus OpenAI Ads in eine eigene Tracking-App, ein CRM-Dashboard oder einen Agenturreport. Wichtig: Die API liefert Reportingdaten, keine personenbezogene Besucherliste.

Ziel

Ziel: Verstehen, wie eine eigene Tracking-App Kosten, Klicks, Impressionen und Conversion-Ergebnisse aus ChatGPT Ads abrufen kann.

Wann dieser Schritt relevant ist

  • Kunden sollen Ergebnisse nicht nur im ChatGPT Ads Manager sehen.
  • Google Ads, Meta Ads, CRM-Leads und OpenAI Ads sollen in einem Dashboard zusammenlaufen.
  • CPA und ROAS sollen intern berechnet werden.

Vorgehen

OpenAI Ads API Key erstellen.

Key nur serverseitig als Secret speichern (<OPENAI_ADS_API_KEY>).

Ad Account und Kampagnen-IDs als Stammdaten speichern.

Insights täglich per Job synchronisieren.

Conversion Insights als eigene Abfrage ergänzen.

Rohdaten lokal speichern statt Dashboards live aus der API zu laden.

Eigene KPIs wie CTR, CPC, CPA und ROAS lokal berechnen.

Reporting-Verzögerungen im eigenen Report erklären.

Pull-Reporting statt Event-Senden

  • Pixel und Conversions API liefern Events an OpenAI.
  • Die Insights API liest aggregierte Werte: Account-, Campaign-, Ad-Group- oder Ad-Level.
  • Conversion Insights werden separat betrachtet und abgefragt.

Empfohlene Datenstruktur

  • Stammdaten: platform, ad_account_id, campaign_id, campaign_name, ad_group_id, ad_id.
  • Kennzahlen pro Tag: date, impressions, clicks, spend, conversions, click_through_conversions, view_through_conversions, revenue, currency.
  • Technisches Feld: synced_at für den Zeitpunkt des letzten Syncs.

Reporting-Hinweise

  • Click-through Conversions nicht mit View-through Conversions vermischen.
  • Attributed Conversions können verzögert erscheinen – 24–48 Stunden Verzögerung in der eigenen Doku erklären.
  • Spend, Clicks und Conversions können unterschiedliche Aktualisierungsrhythmen haben.

Codebeispiele

  • Alle IDs und Keys sind Platzhalter und müssen aus dem eigenen Konto stammen.
Kampagnen-Insights abrufen
curl -sS -G "https://api.ads.openai.com/v1/ad_account/insights" \
  -H "Authorization: Bearer <OPENAI_ADS_API_KEY>" \
  --data-urlencode 'time_granularity=daily' \
  --data-urlencode 'aggregation_level=campaign' \
  --data-urlencode 'fields[]=metadata.readable_time' \
  --data-urlencode 'fields[]=campaign.id' \
  --data-urlencode 'fields[]=campaign.name' \
  --data-urlencode 'fields[]=campaign.impressions' \
  --data-urlencode 'fields[]=campaign.clicks' \
  --data-urlencode 'fields[]=campaign.spend' \
  --data-urlencode 'time_ranges[]={"type":"unix_range","start":1777075200,"end":1777248000}'
Conversion Insights abrufen
curl -sS -X POST "https://api.ads.openai.com/v1/conversions/insights" \
  -H "Authorization: Bearer <OPENAI_ADS_API_KEY>" \
  -H "Content-Type: application/json" \
  --data '{
    "aggregation_level": "campaign",
    "time_ranges": ["{\"type\":\"unix_range\",\"start\":1777075200,\"end\":1777248000}"],
    "entity_ids": ["<CAMPAIGN_ID>"]
  }'

Tageswerte lokal speichern, damit Reports unabhängig von API-Limits bleiben.

Lokale Tabelle für Tracking-Apps
ad_platform_daily_metrics
- platform: openai_ads
- ad_account_id
- campaign_id
- campaign_name
- ad_group_id
- ad_id
- date
- impressions
- clicks
- spend
- conversions
- click_through_conversions
- view_through_conversions
- revenue
- currency
- synced_at

Prüfpunkte

  • Richtung ist klar getrennt: Conversions API sendet, Insights API liest.
  • API Key liegt nur serverseitig.
  • Tageswerte werden lokal gespeichert.
  • Stammdaten (Account, Kampagnen, Ad Groups, Ads) sind gespeichert.
  • Spend, Impressions und Clicks werden importiert.
  • Conversion Insights sind ergänzt.
  • Click-through und View-through Conversions sind getrennt.
  • Reporting-Verzögerungen sind dokumentiert.
  • CPA und ROAS werden transparent berechnet.

Häufige Fehler

  • API-Key im Browser verwenden.
  • Jedes Dashboard live aus der API laden statt lokal zu speichern.
  • Conversions mit Umsatz verwechseln.
  • Click-through und View-through Conversions vermischen.
  • Fehlende Zeitfenster oder unklare Zeitzone.
  • Keine Fehler- und Retry-Logik im Sync-Job.

Praxis-Hinweis

Für Version 1 reicht ein täglicher Sync auf Kampagnen-Level. Erst wenn echte Daten da sind, Ad-Group- und Ad-Level tiefer aufbauen.

Relevante Quellen