Rufe Event-Daten aus deinem Workspace-Pixel-Tracking ab. Events umfassen Pageviews, Klicks und vom Pixel erfasste Custom-Events.

Käufe sind keine Events. Conversions — purchase, lead, subscribe — liegen getrennt und kommen über /v3/conversions. /v3/events?name=purchase liefert bei nahezu jedem Workspace eine leere Liste.

Query-Parameter

Beispiele für den Name-Filter

curl -X GET "https://api.adverfly.com/v3/events?start_date=2024-01-01&end_date=2024-01-31&name=survey_*&limit=100" \
  -H "x-api-key: dein-api-key" \
  -H "client-secret: dein-client-secret"

{
  "data": [
    {
      "store_id": 12345,
      "dt": "2024-01-15 10:30:00",
      "name": "pageview",
      "session_id": 789012345,
      "visitor_id": 456789012,
      "visitor_timezone": "Europe/Berlin",
      "adv_source": "meta",
      "adv_campaign_id": "120210123456789",
      "adv_adgroup_id": "120210987654321",
      "adv_ad_id": "120210111222333",
      "adv_asset_group_id": "6502489623",
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "winter_sale",
      "utm_content": "video_ad_1",
      "utm_term": "",
      "device_type": "desktop",
      "country_code": "DE",
      "hostname": "example.com",
      "pathname": "/products",
      "referrer": "https://google.com",
      "entry_meta_keys": ["fbclid", "gclid"],
      "entry_meta_values": ["abc123", ""]
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "has_more": true,
    "next_offset": 100,
    "start_date": "2024-01-01 00:00:00",
    "end_date": "2024-01-31 23:59:59"
  }
}

Response-Felder

Greife auf Session-Daten und Nutzeraktivität zu. Eine Session repräsentiert den Besuch eines Nutzers auf deiner Website und bündelt mehrere Events.

Query-Parameter

curl -X GET "https://api.adverfly.com/v3/sessions?start_date=2024-01-01&end_date=2024-01-31&limit=100" \
  -H "x-api-key: dein-api-key" \
  -H "client-secret: dein-client-secret"

{
  "data": [
    {
      "store_id": 12345,
      "visitor_id": 456789012,
      "session_id": 789012345,
      "session_start_dt": "2024-01-15 10:25:00",
      "session_end_dt": "2024-01-15 10:45:00",
      "session_duration_seconds": 1200,
      "is_bounce": 0,
      "session_entry_page": "/",
      "session_exit_page": "/checkout/success",
      "events": 12,
      "pageviews": 8,
      "add_to_carts": 1,
      "initiated_checkouts": 1,
      "view_contents": 3,
      "contacts": 0,
      "newsletter_signups": 0,
      "completed_registrations": 0,
      "app_installs": 0,
      "add_payment_infos": 1,
      "adv_source": "meta",
      "adv_campaign_id": "120210123456789",
      "adv_adgroup_id": "120210987654321",
      "adv_ad_id": "120210111222333",
      "adv_asset_group_id": "6502489623",
      "utm_source": "facebook",
      "utm_campaign": "winter_sale",
      "utm_medium": "cpc",
      "utm_content": "video_ad_1",
      "utm_term": "",
      "device_type": "desktop",
      "country_code": "DE",
      "referrer": "https://google.com",
      "pathname": "/products",
      "hostname": "example.com",
      "entry_meta_keys": ["fbclid"],
      "entry_meta_values": ["abc123"]
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "has_more": true,
    "next_offset": 100,
    "start_date": "2024-01-01 00:00:00",
    "end_date": "2024-01-31 23:59:59"
  }
}

Response-Felder

Hole Conversion-Event-Daten deines Workspaces. Conversions werden erfasst, wenn Nutzer gewünschte Aktionen abschließen — Käufe, Anmeldungen, Form-Submits.

Query-Parameter

curl -X GET "https://api.adverfly.com/v3/conversions?start_date=2024-01-01&end_date=2024-01-31&limit=100" \
  -H "x-api-key: dein-api-key" \
  -H "client-secret: dein-client-secret"

{
  "data": [
    {
      "store_id": 12345,
      "dt": "2024-01-15 10:42:00",
      "name": "purchase",
      "session_id": 789012345,
      "customer_id": "customer@email.com",
      "visitor_id": 456789012,
      "transaction_id": "ORD-2024-001",
      "is_new_customer": 1,
      "transaction_gross_revenue": 12999,
      "transaction_currency": "EUR",
      "transaction_country_code": "DE",
      "transaction_city": "Berlin",
      "hostname": "example.com",
      "adv_source": "creator",
      "adv_campaign_id": "",
      "adv_adgroup_id": "",
      "adv_ad_id": "",
      "utm_source": "instagram",
      "utm_medium": "creator",
      "utm_campaign": "spring_launch",
      "utm_content": "",
      "utm_term": ""
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "has_more": true,
    "next_offset": 100,
    "start_date": "2024-01-01 00:00:00",
    "end_date": "2024-01-31 23:59:59",
    "sources": null
  }
}

Response-Felder

Nach Kanal filtern

Mit source bekommst du nur Conversions aus einem bestimmten Kanal — zum Beispiel jeden Kauf, der über Creator kam:

curl -X GET "https://api.adverfly.com/v3/conversions?source=creator&name=purchase&start_date=2024-01-01&end_date=2024-01-31&limit=500" \
  -H "x-api-key: dein-api-key" \
  -H "client-secret: dein-client-secret"

source=creator matcht auch Zeilen von vor dem Rename am 24.07.2026, die noch adv_source: "influencer" tragen — du musst nie beide Schreibweisen anfragen.

Kanäle ausschließen

exclude_source entfernt Kanäle statt sie auszuwählen — der übliche Fall ist „alles außer organic":

curl -X GET "https://api.adverfly.com/v3/conversions?name=purchase&exclude_source=organic&group_by=adv_source&start_date=2024-01-01&end_date=2024-01-31" \
  -H "x-api-key: dein-api-key" \
  -H "client-secret: dein-client-secret"

Eine Session ohne Source zählt als organic — exakt wie im Dashboard. exclude_source=organic wirft also auch ungetaggten Traffic raus, source=organic gibt ihn zurück. Das ist meist der größte Bucket, der Unterschied ist damit nicht kosmetisch.

exclude_source greift nach source und wird nie durch Permissions erweitert: Es kann nur einschränken, was ein Key ohnehin sieht.

Beachte: Ausgeschlossen werden Conversions, deren eigene Session aus dem Kanal kam. Die gleichnamige Attributions-Einstellung im Dashboard arbeitet eine Ebene tiefer — sie nimmt den Kanal aus dem Attributionspfad, sodass die Gutschrift an den vorherigen zulässigen Touchpoint wandert. Bei einem Single-Touch-Endpoint ist das deckungsgleich, unter einem Multi-Touch-Modell nicht.

Breakdowns

Mit group_by bekommst du aggregierte Zeilen statt einer Zeile pro Conversion — zum Beispiel Umsatz pro Creator:

curl -X GET "https://api.adverfly.com/v3/conversions?source=creator&name=purchase&group_by=utm_campaign&start_date=2024-01-01&end_date=2024-01-31" \
  -H "x-api-key: dein-api-key" \
  -H "client-secret: dein-client-secret"

{
  "data": [
    {
      "utm_campaign": "spring_launch",
      "conversions": 73,
      "revenue": 911545,
      "new_customers": 45,
      "unique_customers": 73
    }
  ],
  "pagination": { "limit": 100, "offset": 0, "has_more": false, "next_offset": null }
}

Aggregat-Werte sind JSON-Zahlen. Zeilen-Antworten liefern IDs und Zähler weiterhin als Strings — so war es immer, und eine group_by-Antwort ist eine neue Form, die das nicht erbt.

Dimensionen lassen sich kombinieren — group_by=utm_campaign,date liefert eine Zeile pro Creator pro Tag. Sortiert wird nach Umsatz, außer date ist dabei: dann chronologisch.

Das ist nicht, was die Creators-App ausweist. Ein Breakdown hier zählt Käufe, deren eigene Session den Creator-Tag trug. Die App schreibt einem Creator-Touchpoint bis zum Ende des Attributionsfensters vor dem Kauf gut — wer über einen Creator kommt und drei Tage später über ein Lesezeichen kauft, zählt für die App und hier nicht. Auf einem echten Workspace ist der Unterschied ein Vielfaches, keine Rundungsdifferenz. Für Zahlen, die zur App passen, nimm /v3/report.

Welche Dimension „ein Creator" ist, hängt vom Tagging eurer Links ab. Die meisten Workspaces schreiben den Creator in utm_campaign (danach bricht auch die Creators-App auf), manche nutzen utm_content. Ein einmaliges group_by=utm_campaign,utm_content zeigt dir, welches Feld die Namen trägt.

Hinweise

• Umsatz wird in der kleinsten Währungs-Einheit (Cent) zurückgegeben. Teile durch 100 für den Hauptwert.
• Verwende transaction_id oder customer_id, um spezifische Bestellungen oder Kunden zu finden.
• Die Kanal-Felder beschreiben die Session, in der die Conversion passiert ist — Last Touch auf Session-Ebene. Das ist kein Multi-Touch-Modell: Ein Kauf, dessen Besucher zuerst über einen Creator kam und später direkt zurückkehrte, zählt hier als Direct. Für First-Click, Linear oder U-Shaped nutze den MCP-Server.
• Ein unbekannter Wert in source liefert 400 statt ignoriert zu werden — ein Tippfehler kann das Ergebnis also nie still auf alle Kanäle ausweiten.

Hole Werbeperformance-Daten deines Workspaces. Liefert Spend, Impressions, Clicks und Reach von verbundenen Werbeplattformen (Meta, Google, TikTok etc.).

Query-Parameter

Unterstützte Sources

curl -X GET "https://api.adverfly.com/v3/ads?start_date=2024-01-01&end_date=2024-01-31&source=meta,google&limit=100" \
  -H "x-api-key: dein-api-key" \
  -H "client-secret: dein-client-secret"

{
  "data": [
    {
      "store_id": 12345,
      "dt": "2024-01-15",
      "adaccount_id": "act_123456789",
      "source": "meta",
      "campaign_id": "120210123456789",
      "campaign_name": "Winter Sale 2024",
      "adgroup_id": "120210987654321",
      "adgroup_name": "Lookalike - Purchases",
      "ad_id": "120210111222333",
      "ad_name": "Video - Snow Jacket",
      "spend": 4500,
      "impressions": 12340,
      "clicks": 287,
      "reach": 9800
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "has_more": true,
    "next_offset": 100,
    "start_date": "2024-01-01 00:00:00",
    "end_date": "2024-01-31 23:59:59",
    "sources": ["meta", "google"]
  }
}

Response-Felder

Totals

Der Ads-Endpunkt liefert zusätzlich ein totals-Objekt auf Top-Level mit aggregierten Werten:

{
  "totals": {
    "total_ads": 500,
    "total_spend": 123456,
    "total_impressions": 9876543,
    "total_clicks": 54321,
    "total_reach": 7654321
  },
  "data": [...],
  "pagination": { ... }
}

Hinweise

• Spend wird in der kleinsten Währungs-Einheit (z. B. Cent) zurückgegeben. Teile durch 100 für den Hauptwert.
• Reach kann 0 sein, wenn die Plattform es nicht meldet (z. B. Google Ads).
• Daten sind pro Ad pro Tag dedupliziert. Werden die gleichen Ad-Daten mehrfach importiert, wird nur die neueste Version zurückgegeben.
• Erfordert die Berechtigung read:<source> oder admin:admin für deinen API-Key.

Liefert dieselben Aggregate wie dein Dashboard — Metriken × Breakdown × Attributionsmodell — statt roher Zeilen.

Der Endpoint rechnet nichts Eigenes. Er nutzt die Query-Engine hinter /summary und /insights und wendet die Display-Settings deines Workspaces an. Ein /v3/report-Call und der passende Screen liefern damit dieselben Zahlen. Nimm /v3/conversions für einzelne Conversions und /v3/report, wenn die Summen mit der UI übereinstimmen müssen.

Query-Parameter

Verfügbare Metriken

spend, revenue, roas, ctr, cpa, cr, sessions, conversions, impressions, clicks, new_customers, add_to_carts, checkouts

Die Profit-Ladder — cogs, payment_fees, shipping_costs, refunds, gross_profit, contribution_profit, net_profit, gross_margin, net_margin, net_roas — braucht die read:profit-Permission auf dem API-Key. Ohne sie liefert eine solche Anfrage 403.

curl -X GET "https://api.adverfly.com/v3/report?metrics=revenue,conversions,roas&breakdown=utm_campaign&source=creator&attribution_model=first_click&attribution_window=1&exclude_source=organic&name=purchase&start_date=2024-01-24&end_date=2024-01-30" \
  -H "x-api-key: dein-api-key" \
  -H "client-secret: dein-client-secret"

{
  "data": [
    {
      "utm_campaign": "spring_launch",
      "revenue": 9115.45,
      "conversions": 73,
      "roas": 4.2
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "has_more": false,
    "next_offset": null,
    "total_rows": 1,
    "start_date": "2024-01-24 00:00:00",
    "end_date": "2024-01-30 23:59:59",
    "sources": ["creator", "influencer"],
    "ignored_sources": ["organic"]
  }
}

Was aus den Workspace-Settings kommt

Diese werden pro Request gelesen und genau so angewendet wie im Dashboard — sie sind keine Parameter:

• Include Unattributed — ob plattformseitige Bestellungen ohne Pixel-Match eine eigene Zeile bekommen
• Net-Merchandise-Revenue — ob Steuer und Versand vom Umsatz abgezogen werden
• Refund-Netting, ausgeschlossene Transaktions-IDs, Plattform-Umsatz-Auflösung und die Neukunden-Korrektur passieren in der Engine

Änderst du sie in den Workspace-Einstellungen, folgt der Endpoint beim nächsten Call. Das ist der Deal: Parität mit der UI statt unabhängig einstellbarer API.

report vs. conversions

Hinweise

• Geldwerte kommen in der Workspace-Währung, nicht in Cent — 9115.45 heißt 9.115,45 €. Das unterscheidet sich von /v3/conversions, das rohe Pixel-Werte in Cent liefert. Verhältnis-Metriken (roas, net_roas) sind Faktoren, Prozentwerte (ctr, cr, gross_margin, net_margin) sind Anteile: 0.2641 bedeutet 26,41 %.
• Eine Metrik, die für eine Zeile nicht berechenbar ist — ROAS ohne Spend, CR ohne Sessions — kommt als null zurück, nicht als 0. Ein Kanal ohne Daten sieht damit nicht wie ein Kanal mit Null-Performance aus.
• exclude_source nimmt hier den Kanal aus dem Attributionspfad, nicht die Zeile — die Gutschrift wandert zum vorherigen zulässigen Touchpoint. Auf /v3/conversions entfernt derselbe Parameter Zeilen. Die Benennung folgt dem Dashboard, wo die Einstellung ebenfalls eine Attributions-Einstellung ist.
• Wer den Creator-Kanal ausschließt, schließt creator und influencer aus — Daten von vor dem Rename werden also nicht halb mitgezählt.
• Paginiert wird über die aggregierten Zeilen; total_rows sagt dir, wie viele Gruppen der Breakdown erzeugt hat.

Die Adverfly-API verwendet Standard-HTTP-Statuscodes, um Erfolg oder Fehlschlag von Anfragen anzuzeigen.

HTTP-Statuscodes

Fehler-Response-Format

Bei einem Fehler liefert die API ein JSON-Objekt mit einem message-Feld:

{
  "message": "Invalid API key"
}

Häufige Fehlermeldungen

Berechtigungen

API-Keys nutzen ein Source-basiertes Berechtigungs-System. Jeder Key kann Berechtigungen wie read:meta, read:google etc. haben. admin:admin gibt Vollzugriff auf alle Sources.

read:creators gibt den Creator-Kanal frei — ein Key mit nur dieser Berechtigung liest Creator-Traffic und sonst nichts.

Wenn du Ads von einer Source anfragst, für die dein Key keine Berechtigung hat, erhältst du einen 403 Forbidden-Response.

Adverfly stellt seine Analytics-Tools als Model-Context-Protocol-Server bereit. Jeder MCP-kompatible Client (Claude Desktop, Cursor, Custom-Agents) kann deine Workspace-Daten mit denselben Tools abfragen, die auch der in-product Cortex-Agent nutzt — Analytics, MMM-Ergebnisse, Empfehlungen, Attribution, Creative-Performance und mehr.

Was es kann

• Read-Only-Zugriff auf jedes Cortex-Analytics-Tool, via JSON-RPC 2.0
• Workspace-scoped — der API-Key bestimmt den Workspace (oder mehrere, siehe unten)
• Gleiches Permission-Modell wie die Data-API (Quellen-Zugriff per Key-Permissions)

Zusätzlich ist ein kleines Set draft-sicherer Write-Tools verfügbar: Custom Reports und (standardmäßig deaktivierte) Workflows anlegen sowie Canvas-Listen bauen — Listen/Whiteboards erstellen, Spalten und Zeilen hinzufügen, Top-Creatives verlinken. Listen-Writes sind rein additiv; Delete-Tools gibt es nicht. Andere Side-Effect-Tools (Notiz speichern, Bild generieren, Export senden) bleiben unexposed.

Authentifizierung

API-Key + Client-Secret in einem einzigen Bearer-Header:

Authorization: Bearer <api_key>:<client_secret>

Die beiden Werte werden mit Doppelpunkt getrennt. Alternativ funktionieren die Standard-Header x-api-key + client-secret, falls dein MCP-Client das bevorzugt.

Credentials in Workspace-Einstellungen → API-Keys erzeugen.

Mehrere Workspaces über eine Verbindung

Bei der Verbindung via OAuth (der "Add Custom Connector"-Flow in claude.ai) lässt der Consent-Screen die Auswahl mehrerer Workspaces für eine einzige Verbindung zu — analog zu Metas MCP über mehrere Werbekonten. Auf einer Multi-Workspace-Verbindung gilt:

• Jedes Tool bekommt einen Pflicht-Parameter workspace_id, der den Call an einen Workspace routet
• Ein workspaces_list-Tool liefert die autorisierten Workspaces (ID + Name)
• Jeder Workspace behält seinen eigenen Permission-Snapshot — der Zugriff entspricht deiner Rolle im jeweiligen Workspace zum Verbindungszeitpunkt

Verbindungen mit nur einem Workspace bleiben unverändert: kein workspace_id-Parameter, kein workspaces_list-Tool.

Methoden

JSON-RPC 2.0. Drei Methoden:

Anbindung an Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json bearbeiten:

{
  "mcpServers": {
    "adverfly": {
      "url": "https://api.adverfly.com/mcp",
      "headers": {
        "Authorization": "Bearer <api_key>:<client_secret>"
      }
    }
  }
}

Claude Desktop neu starten. Die Adverfly-Tools tauchen im Tool-Menü auf, Claude kann sie im Chat callen.

Anbindung an Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "adverfly": {
      "url": "https://api.adverfly.com/mcp",
      "headers": {
        "Authorization": "Bearer <api_key>:<client_secret>"
      }
    }
  }
}

Schnelltest aus dem Terminal

Tools auflisten:

curl -X POST https://api.adverfly.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <api_key>:<client_secret>' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Tool callen — z. B. Analytics-Query für die letzten 7 Tage:

curl -X POST https://api.adverfly.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <api_key>:<client_secret>' \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"tools/call",
    "params":{
      "name":"analytics.query",
      "arguments":{
        "metrics":["spend","revenue","roas"],
        "filters":{"date_from":"2026-05-10","date_to":"2026-05-17"}
      }
    }
  }'

Verfügbare Tools

Die MCP-Oberfläche startet bewusst klein. tools/list callen für die aktuelle Liste.

v1 — ein Tool:

• analytics.query — flexible Query für jede Metrik (Spend, Revenue, ROAS, Sessions, Conversions, Profit-Ladder, etc.) × Breakdown (Channel, Campaign, Creative, Country, …) × Zeitraum × Source-Filter.
• analytics.profit-summary — komplette Profit-Ladder für einen Zeitraum: Revenue, Refunds, COGS, Payment-Fees, Versandkosten, Gross-/Contribution-/Net-Profit, Margen und Net-ROAS.

Profit-Metriken (cogs, payment_fees, gross_profit, contribution_profit, net_profit, gross_margin, net_margin, net_roas) benötigen die read:profit-Permission auf dem API-Key — ohne sie liefern Profit-Anfragen einen Permission-Fehler.

Dieses eine Tool deckt die meisten „zeig mir X"-Fragen ab.

Canvas-Listen-Tools (Write, rein additiv):

• lists.get-lists — alle Canvas-Listen mit Spalten und Items
• lists.create — neue Liste oder Whiteboard (kind), optional in einem Ordner
• lists.add-column / lists.add-items / lists.update-items — Spalten und Zeilen aufbauen; Zeilen können Workspace-Entitäten verlinken (Creatives, Kampagnen, Produkte, …)
• lists.add-top-creatives — One-Shot: rankt die Creatives des Workspace nach ROAS/Revenue/Spend/CTR und fügt die Top N als verlinkte Zeilen hinzu

Delete-Tools gibt es bewusst nicht — eine falsche Zeile wird im Canvas-UI entfernt. Andere Side-Effect-Tools bleiben in der in-product MCP-App mit Approval-Gate.

Fehler-Responses

JSON-RPC-Fehler-Envelope:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": { "code": -32001, "message": "Invalid API key" }
}

HTTP-Status ist 200 für alle JSON-RPC-Responses (auch Errors) — Fehler-Detail steht im error-Feld.