Wie viele APIs hat OpenAI Ads?

Zwei: die Conversions API für Server-Events (bzr.openai.com) und die Advertiser API für Konto, Kampagnen, Ad Groups, Ads und Reporting (api.ads.openai.com). Insights ist keine eigene API, sondern ein Endpunkt der Advertiser API. Das Measurement Pixel ist ein Browser-Snippet und zählt nicht als API.

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

Die Advertiser API mit ihren Insights-Endpunkten. 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 Advertiser API Key und Conversions API Key?

Der Advertiser API Key authentifiziert Requests gegen api.ads.openai.com – inklusive der Insights-Endpunkte – 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 ist ein Endpunkt der Advertiser API und liefert die Performance-Daten.
Advertiser 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 (keine API)	Browser-Tracking	Browser / Website	`Pixel ID (öffentlich im Snippet)`	Landingpages, Danke-Seiten, einfache Events
API 1: Conversions API	Server-Events senden	Nur Server / Backend	`https://bzr.openai.com/v1/events?pid=<PIXEL_ID>`	Käufe, Leads, CRM-Qualifizierung
API 2: Advertiser API	Konto, Kampagnen, Ad Groups und Ads verwalten	Server / technische Tools	`https://api.ads.openai.com/v1`	Automatisierung und technische Verwaltung
→ Insights (Endpunkt der Advertiser API)	Reporting lesen	Server / Sync-Job	`https://api.ads.openai.com/v1/.../insights`	Tracking-App, Dashboard, Data Warehouse

Die Advertiser 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 die Advertiser API inklusive Insights. Jeder Advertiser 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: Advertiser 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-Endpunkt

Die Advertiser API liefert aggregierte Reportingdaten über ihre Insights-Endpunkte: 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

Advertiser 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

Wie viele APIs hat OpenAI Ads?: Zwei: die Conversions API für Server-Events (bzr.openai.com) und die Advertiser API für Konto, Kampagnen, Ad Groups, Ads und Reporting (api.ads.openai.com). Insights ist keine eigene API, sondern ein Endpunkt der Advertiser API. Das Measurement Pixel ist ein Browser-Snippet und zählt nicht als API.
Welche API brauche ich für Reporting-Daten aus OpenAI Ads?: Die Advertiser API mit ihren Insights-Endpunkten. 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 Advertiser API Key und Conversions API Key?: Der Advertiser API Key authentifiziert Requests gegen api.ads.openai.com – inklusive der Insights-Endpunkte – 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.