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

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",
      "transaction_gross_revenue": 12999,
      "transaction_currency": "EUR",
      "transaction_country_code": "DE",
      "transaction_city": "Berlin",
      "hostname": "example.com"
    }
  ],
  "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

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.

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.

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.

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
• Gleiches Permission-Modell wie die Data-API (Quellen-Zugriff per Key-Permissions)

Write-Tools (Notiz speichern, Bild generieren, Export senden) sind via MCP nicht verfügbar.

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.

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, etc.) × Breakdown (Channel, Campaign, Creative, Country, …) × Zeitraum × Source-Filter.

Dieses eine Tool deckt die meisten „zeig mir X"-Fragen ab. Mehr kommen, sobald Kunden danach fragen — Write- und Side-Effect-Tools bleiben voraussichtlich 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.