Retrieve event data from your workspace pixel tracking. Events include pageviews, clicks, and custom events tracked by your pixel.

Purchases are not events. Conversions — purchase, lead, subscribe — are stored separately and returned by /v3/conversions. Querying /v3/events?name=purchase returns an empty list on almost every workspace.

Query Parameters

Name filter examples

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: your-api-key" \
  -H "client-secret: your-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 Fields

Access session data and user activity information. A session represents a user's visit to your website, grouping multiple events together.

Query Parameters

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: your-api-key" \
  -H "client-secret: your-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 Fields

Get conversion event data for your workspace. Conversions are tracked when users complete desired actions like purchases, signups, or form submissions.

Query Parameters

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: your-api-key" \
  -H "client-secret: your-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 Fields

Filtering by channel

Pass source to return only conversions from a given acquisition channel — for example every purchase driven by a creator:

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: your-api-key" \
  -H "client-secret: your-client-secret"

source=creator also matches rows recorded before the 2026-07-24 rename, which carry adv_source: "influencer" — you never have to ask for both spellings.

Excluding channels

exclude_source removes channels instead of selecting them — the usual case being "everything except 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: your-api-key" \
  -H "client-secret: your-client-secret"

A session with no source counts as organic, exactly as it does in the dashboard — so exclude_source=organic also drops untagged traffic, and source=organic returns it. This is usually the largest bucket, so the difference is not cosmetic.

exclude_source runs after source and is never widened by permissions: it can only narrow what a key already sees.

Note that this excludes conversions whose own session came from that channel. The dashboard's attribution setting of the same name works one level deeper — it drops the channel from the attribution path so credit moves to the previous eligible touchpoint. With a single-touch endpoint the two agree; under a multi-touch model they do not.

Breakdowns

Add group_by to get aggregated rows instead of one row per conversion — for example revenue per 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: your-api-key" \
  -H "client-secret: your-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 }
}

Aggregate values are JSON numbers. Row-level responses keep IDs and counters as strings, which is how they have always been returned — a group_by response is a new shape, so it does not inherit that.

Dimensions combine — group_by=utm_campaign,date gives one row per creator per day. Rows are sorted by revenue, except when date is among the dimensions, where they are sorted chronologically.

This is not what the Creators app reports. A breakdown here counts purchases whose own session carried the creator tag. The app credits a creator touchpoint up to the attribution window before the purchase, so a visitor who arrives through a creator and buys three days later from a bookmark counts for the app and not here. On a real workspace the difference is a multiple, not a rounding error. Use /v3/report for numbers that match the app.

Which dimension is "a creator" depends on how your links are tagged. Most workspaces put the creator in utm_campaign (this is what the Creators app breaks down by), some use utm_content. Run group_by=utm_campaign,utm_content once to see which field carries the names.

Notes

• Revenue is returned in the smallest currency unit (cents). Divide by 100 for the main currency value.
• Use transaction_id or customer_id filters to look up specific orders or customers.
• Channel fields describe the session the conversion happened in — session-level last touch. They are not a multi-touch attribution model: a purchase whose visitor first arrived through a creator and returned later via a direct visit is reported as direct here. For first-click, linear or U-shaped attribution use the MCP server.
• An unknown value in source returns 400 rather than being ignored, so a typo can never silently widen the result to all channels.

Get advertising performance data for your workspace. Returns spend, impressions, clicks, and reach from connected ad platforms (Meta, Google, TikTok, etc.).

Query Parameters

Supported 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: your-api-key" \
  -H "client-secret: your-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 Fields

Totals

The ads endpoint also returns a totals object at the top level with aggregated values:

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

Notes

• Spend is returned in the smallest currency unit (e.g. cents). Divide by 100 to get the value in the main currency unit.
• Reach may be 0 for platforms that do not report it (e.g. Google Ads).
• Data is deduplicated per ad per day. If the same ad data is imported multiple times, only the latest version is returned.
• Requires read:<source> or admin:admin permission on your API key.

Returns the same aggregates your dashboard shows — metrics × breakdown × attribution model — instead of raw rows.

This endpoint does not compute anything of its own. It runs the query engine behind /summary and /insights and applies your workspace's display settings, so a /v3/report call and the equivalent screen return the same numbers. Use /v3/conversions when you want individual conversions, and /v3/report when you want totals that have to reconcile with the UI.

Query Parameters

Available metrics

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

Profit-ladder metrics — cogs, payment_fees, shipping_costs, refunds, gross_profit, contribution_profit, net_profit, gross_margin, net_margin, net_roas — require the read:profit permission on the API key. Requesting one without it returns 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: your-api-key" \
  -H "client-secret: your-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"]
  }
}

What comes from your workspace settings

These are read per request and applied exactly as the dashboard applies them — they are not parameters:

• Include unattributed — whether platform-side orders without a pixel match get their own row
• Net merchandise revenue — whether tax and shipping are subtracted from revenue
• Refund netting, excluded transaction IDs, platform revenue resolution and the new-customer correction all happen inside the engine

Change them in the workspace settings and this endpoint follows on the next call. That is the trade: parity with the UI, not an independently tunable API.

report vs conversions

Notes

• Money is returned in the workspace currency, not in cents — 9115.45 means 9,115.45 €. This differs from /v3/conversions, which returns raw pixel values in cents. Ratio metrics (roas, net_roas) are plain factors, percentages (ctr, cr, gross_margin, net_margin) are fractions: 0.2641 means 26.41 %.
• A metric that cannot be computed for a row — ROAS without spend, CR without sessions — returns null rather than 0, so an empty channel is not reported as a zero-performance one.
• exclude_source here removes the channel from the attribution path, not the row — credit moves to the previous eligible touchpoint. On /v3/conversions the same parameter removes rows. The names match the dashboard, where the setting is likewise an attribution setting.
• Excluding the creator channel covers both creator and influencer, so pre-rename data is not half-counted.
• Pagination is applied to the aggregated rows, so total_rows tells you how many groups the breakdown produced.

The Adverfly API uses standard HTTP status codes to indicate the success or failure of requests.

HTTP Status Codes

Error Response Format

When an error occurs, the API returns a JSON object with a message field:

{
  "message": "Invalid API key"
}

Common Error Messages

Permissions

API keys use a source-based permission system. Each key can have permissions like read:meta, read:google, etc. Use admin:admin for full access to all sources.

read:creators grants the creator channel — a key holding only that permission reads creator traffic and nothing else.

If you request ads from a source your key does not have permission for, you will receive a 403 Forbidden response.

Adverfly exposes its analytics tools as a Model Context Protocol server. Any MCP-compatible client (Claude Desktop, Cursor, custom agents) can query your workspace data using the same tools the in-product Cortex agent uses — analytics, MMM results, recommendations, attribution, creative performance, and more.

What it gives you

• A read-only view of every Cortex analytics tool, exposed via JSON-RPC 2.0
• Workspace-scoped — the API key picks the workspace (or several, see below)
• Same permission model as the Data API (per-source access controlled by key permissions)

A small set of draft-safe write tools is exposed too: create custom reports and (disabled-by-default) workflows, and build Canvas lists — create lists/whiteboards, add columns and rows, link top creatives. List writes are additive only; there are no delete tools. Other side-effect tools (save note, generate image, send export) stay unexposed.

Authentication

Send your Adverfly API key + client secret in a single Bearer header:

Authorization: Bearer <api_key>:<client_secret>

The two values are separated by a colon. You can also use the standard x-api-key + client-secret headers if your MCP client prefers that.

Generate credentials in Workspace Settings → API Keys.

Multiple workspaces on one connection

When you connect via OAuth (the claude.ai "Add Custom Connector" flow), the consent screen lets you select several workspaces for a single connection — the same way Meta's MCP spans several ad accounts. On a multi-workspace connection:

• Every tool gains a required workspace_id parameter routing the call to one workspace
• A workspaces_list tool returns the authorized workspaces (id + name)
• Each workspace keeps its own permission snapshot — access mirrors your role in that workspace at connect time

Connections scoped to a single workspace are unchanged: no workspace_id parameter, no workspaces_list tool.

Methods

The endpoint speaks JSON-RPC 2.0. Three methods:

Connecting from Claude Desktop

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

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

Restart Claude Desktop. The Adverfly tools appear in the tools menu and Claude can call them in conversation.

Connecting from Cursor

Add to ~/.cursor/mcp.json:

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

Quick test from the terminal

List available tools:

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

Call a tool — e.g. an analytics query for the last 7 days:

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

Available tools

The MCP surface starts small on purpose. Call tools/list to see what's live today.

v1 — one tool:

• analytics.query — flexible query for any metric (spend, revenue, ROAS, sessions, conversions, profit ladder, etc.) × breakdown (channel, campaign, creative, country, …) × date range × source filter × attribution model (last_click, first_click, linear, u_shaped, total_impact). There is no campaign/ad filter parameter — to read a single campaign or ad, set breakdown (e.g. campaign_id) and read that entity's row; the Totals block always covers the whole selected scope.
• analytics.profit-summary — full profit ladder for a date range: revenue, refunds, COGS, payment fees, shipping costs, gross/contribution/net profit, margins and Net-ROAS.

Profit metrics (cogs, payment_fees, gross_profit, contribution_profit, net_profit, gross_margin, net_margin, net_roas) require the read:profit permission on the API key — without it, profit requests return a permission error.

This single tool covers most "show me X" questions.

Canvas list tools (write, additive-only):

• lists.get-lists — all Canvas lists with columns and items
• lists.create — new list or whiteboard (kind), optionally inside a folder
• lists.add-column / lists.add-items / lists.update-items — build out columns and rows; rows can link workspace entities (creatives, campaigns, products, …)
• lists.add-top-creatives — one-shot: rank the workspace's creatives by ROAS/revenue/spend/CTR and add the top N as linked rows

There are deliberately no delete tools — a mistaken row is removed in the Canvas UI. Other side-effect tools stay scoped to the in-product MCP app with its human-approval gate.

Error responses

JSON-RPC error envelope:

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

HTTP status is 200 for all JSON-RPC responses, including errors — check the error field in the body.