Welche API brauche ich für Reporting-Daten aus OpenAI Ads?

Die Insights API. Sie liest aggregierte Performance-Daten über GET-Endpunkte wie /ad_account/insights oder /campaigns/{campaign_id}/insights sowie attributed conversion totals über POST /conversions/insights. Basis-URL ist https://api.ads.openai.com/v1.

Was ist der Unterschied zwischen Ads API Key und Conversions API Key?

Der Ads API Key authentifiziert Requests gegen die Ads/Insights API (api.ads.openai.com) und ist auf ein Ad Account gescoped. Der Conversions API Key authentifiziert Server-Events an den Events-Endpoint (bzr.openai.com). Beide Keys gehören ausschließlich auf den Server.

Kann ich die Conversions API aus dem Browser aufrufen?

Nein. Die Conversions API ist Server-to-Server gedacht. Der Key würde im Browser sichtbar und missbrauchbar. Browser-Tracking läuft über das Measurement Pixel.

Wie teste ich Server-Events, ohne sie zu speichern?

Mit validate_only: true im Request an die Conversions API. Events werden dann nur validiert, nicht gespeichert. Für die Produktion muss validate_only auf false stehen.

OpenAI Ads APIs verständlich erklärt

Kurzfassung

Pixel läuft im Browser.
Conversions API sendet Server-Events an OpenAI.
Insights API liest aggregierte Performance-Daten aus OpenAI Ads.
Ads API Key und Conversions API Key nicht vermischen.
Keys gehören nie ins Frontend.

Welche Schnittstelle brauche ich?

Thema	Zweck	Läuft wo	Key / Endpoint	Typische Nutzung
Measurement Pixel	Browser-Tracking	Browser / Website	`Pixel ID (öffentlich im Snippet)`	Landingpages, Danke-Seiten, einfache Events
Conversions API	Server-Events senden	Nur Server / Backend	`https://bzr.openai.com/v1/events?pid=<PIXEL_ID>`	Käufe, Leads, CRM-Qualifizierung
Insights API	Reporting lesen	Server / Sync-Job	`https://api.ads.openai.com/v1/.../insights`	Tracking-App, Dashboard, Data Warehouse
Ads API (allgemein)	Account, Kampagnen, Ad Groups, Ads verwalten	Server / technische Tools	`https://api.ads.openai.com/v1`	Automatisierung und technische Verwaltung

Die Ads API läuft unter der Basis-URL https://api.ads.openai.com/v1 und authentifiziert über den Header Authorization: Bearer $OPENAI_ADS_API_KEY. Die meisten Endpunkte akzeptieren application/json.

Keys sauber trennen

Drei Werte, drei unterschiedliche Schutzstufen:

<PIXEL_ID> ist öffentlich genug fürs Pixel-Snippet – trotzdem nicht unnötig streuen.
<CONVERSIONS_API_KEY> ist ein Secret für Server-to-Server-Events (Conversions API).
<OPENAI_ADS_API_KEY> ist ein Secret für Ads API und Insights API. Jeder Ads API Key ist auf ein Ad Account gescoped – Agenturen und Partner müssen den Key des jeweiligen Kundenkontos nutzen.

Beide Secret Keys gehören in einen Secret Manager bzw. die Projekt-Secrets: nie in den Browser, nie in Git, nie in Frontend-Code. Pixel ID und Conversions API Key werden im Ads Manager im Conversions-Tab verwaltet bzw. provisioniert.

Faustregel: Alles, was ein Authorization: Bearer-Header braucht, läuft ausschließlich auf dem Server.

Schnelltest: Ads API Key prüfen

Mit GET /ad_account prüfst du, ob dein Bearer Token funktioniert:

ads-api-key-testen.sh

curl -X GET "https://api.ads.openai.com/v1/ad_account" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -H "Accept: application/json"

Die Antwort zeigt u. a. Account-ID, Name, Status, Zeitzone, Währung und Review-Status. Kommt ein Fehler zurück, stimmt Key oder Account-Zuordnung nicht.

Server-Events senden: Conversions API

Die Conversions API ist Server-to-Server: Events werden nur vom Server gesendet, nie aus dem Browser. Erforderlich sind der Query-Parameter pid (deine Pixel ID) und das events-Array.

conversions-api-event.sh

curl -X POST "https://bzr.openai.com/v1/events?pid=<PIXEL_ID>" \
  -H "Authorization: Bearer <CONVERSIONS_API_KEY>" \
  -H "Content-Type: application/json" \
  --data '{
    "validate_only": false,
    "events": [
      {
        "id": "order_12345",
        "type": "order_created",
        "timestamp_ms": <EVENT_TIMESTAMP_MS>,
        "source_url": "https://example.com/checkout/confirmation",
        "action_source": "web",
        "data": {
          "type": "contents",
          "amount": 9900,
          "currency": "EUR"
        }
      }
    ]
  }'

validate_only: true validiert Events, ohne sie zu speichern – ideal für technische Tests.
Batches akzeptieren bis zu 1.000 Events; schlägt ein Event fehl, schlägt der ganze Batch fehl – am Anfang klein halten.
Die Event-id muss mit der Pixel-event_id übereinstimmen, damit Deduplizierung funktioniert.

Reporting lesen: Insights API

Die Insights API liefert aggregierte Reportingdaten über GET /ad_account/insights, /campaigns/{campaign_id}/insights, /ad_groups/{ad_group_id}/insights und /ads/{ad_id}/insights.

insights-tageswerte.sh

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

Conversions Insights lesen

Attributed conversion totals (inkl. Click-through-/View-through-Aufschlüsselung) liefert POST /conversions/insights:

conversions-insights.sh

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",
    "entity_ids": ["<CAMPAIGN_ID>"],
    "time_ranges": ["{\"type\":\"unix_range\",\"start\":1777075200,\"end\":1777248000}"]
  }'

Empfohlene technische Architektur

Frontend

Pixel erst nach Marketing-Consent laden und initialisieren.

Danke-Seite

Browser-Event mit event_id senden (z. B. order_created).

Backend / Shop / CRM

Server-Event über die Conversions API senden – mit derselben ID zur Deduplizierung.

Sync-Job

Insights täglich lesen und lokal speichern (Zeitzone beachten).

Dashboard

Lokale Daten anzeigen – nicht bei jedem Seitenaufruf live die API abfragen.

Fehler, die teuer werden

Ads API Key im Frontend-Code (wird so sichtbar und missbrauchbar).
Conversions API Key im Pixel-Code oder im Browser.
Pixel ID und API Key verwechselt.
Zu große Batches: Schlägt ein Event fehl, schlägt der ganze Batch fehl (max. 1.000 Events).
validate_only: true versehentlich produktiv gelassen – dann wird nichts gespeichert.
Daten mit falscher Zeitzone oder falscher Range synchronisiert.
Reporting bei jedem Seitenaufruf live aus der API laden statt lokal zu speichern.

Alle Codebeispiele auf dieser Seite nutzen ausschließlich Platzhalter wie <PIXEL_ID>, <CONVERSIONS_API_KEY> und <CAMPAIGN_ID>. Ersetze sie nur serverseitig durch echte Werte aus deinem Secret Manager.

Weiterführende Kapitel

Häufige Fragen

Welche API brauche ich für Reporting-Daten aus OpenAI Ads?: Die Insights API. Sie liest aggregierte Performance-Daten über GET-Endpunkte wie /ad_account/insights oder /campaigns/{campaign_id}/insights sowie attributed conversion totals über POST /conversions/insights. Basis-URL ist https://api.ads.openai.com/v1.
Was ist der Unterschied zwischen Ads API Key und Conversions API Key?: Der Ads API Key authentifiziert Requests gegen die Ads/Insights API (api.ads.openai.com) und ist auf ein Ad Account gescoped. Der Conversions API Key authentifiziert Server-Events an den Events-Endpoint (bzr.openai.com). Beide Keys gehören ausschließlich auf den Server.
Kann ich die Conversions API aus dem Browser aufrufen?: Nein. Die Conversions API ist Server-to-Server gedacht. Der Key würde im Browser sichtbar und missbrauchbar. Browser-Tracking läuft über das Measurement Pixel.
Wie teste ich Server-Events, ohne sie zu speichern?: Mit validate_only: true im Request an die Conversions API. Events werden dann nur validiert, nicht gespeichert. Für die Produktion muss validate_only auf false stehen.