RevPanel API

Read your Meta, Google Ads, TikTok, Search Console and Google Analytics numbers from one place, organized by product. Use the REST API to send them to your own tools, or the MCP server to ask your AI assistant about them.

Overview

  • Base URL: https://revpanel.co/api/v1. Every endpoint returns JSON.
  • Read only. RevPanel can read reports from your ad accounts but cannot create, change, pause or delete anything in them.
  • One set of reports, two ways in. Each REST endpoint is the same report as the MCP tool of the same name, with the same parameters and the same numbers.
  • Every ratio (CTR, CPC, CPM, CPA, ROAS, conversion rate) is computed on our side from sums. Use the values as given; averaging ratios across rows gives wrong answers.
  • A machine-readable description is at /api/v1/openapi.json (OpenAPI 3.1), for Postman, n8n, code generators and AI agents.

Quickstart

  1. Sign in to RevPanel and connect your ad accounts under Connections.
  2. Open Connect to AI and create a key. Copy it: it is shown once. A key can cover the whole workspace or a single project.
  3. Ask for last week's spend by day and platform:
curl "https://revpanel.co/api/v1/performance?date_preset=last_7d&group_by=day,platform" \
  -H "Authorization: Bearer $REVPANEL_API_KEY"

A response looks like this (one campaign on one day):

{
  "meta": {
    "since": "2026-11-12",
    "until": "2026-11-12",
    "days": 1,
    "timeZones": ["America/New_York"],
    "currencies": ["USD"],
    "conversionEvents": { "My Shop": "purchase" },
    "scope": "whole workspace",
    "warnings": []
  },
  "totals": [
    {
      "currency": "USD",
      "metrics": { "spend": 120.5, "impressions": 9800, "clicks": 214, "conversions": 6, "conversionValue": 540,
                   "ctr": 0.0218, "cpc": 0.56, "cpm": 12.3, "cpa": 20.08, "roas": 4.48, "conversionRate": 0.028 }
    }
  ],
  "rows": [
    {
      "day": "2026-11-12", "platform": "meta", "campaign": "Shop | Prospecting", "currency": "USD",
      "spend": 120.5, "impressions": 9800, "clicks": 214, "conversions": 6, "conversionValue": 540,
      "ctr": 0.0218, "cpc": 0.56, "cpm": 12.3, "cpa": 20.08, "roas": 4.48, "conversionRate": 0.028,
      "reach": 7100, "frequency": 1.38
    }
  ],
  "truncated": null
}

Authentication

Send your key in the Authorization header on every request: Authorization: Bearer sc_live_…. Keys never appear in URLs. Keep them on a server: do not put a key in a web page or a mobile app.

A key limited to one project only sees that project's data. Revoke a key at any time under Connect to AI; it stops working at once. The same keys work for the MCP server.

Dates, money and freshness

  • Choose a period with date_preset (for example last_7d, which is the 7 complete days ending yesterday) or with since and until (YYYY-MM-DD, inclusive). Dates are calendar days in each ad account's own time zone.
  • Money is in each ad account's own currency and is never converted. Totals are listed per currency; never add amounts in different currencies.
  • Every result has a meta block with the exact dates, time zones, currencies and warnings, such as a partial day or an account that needs reconnecting. Check it.
  • Conversions and conversion value are what each ad platform attributes to its ads, counted from each project's own conversion event (meta.conversionEvents). They are not verified revenue.
  • Numbers older than an hour are refreshed from the platforms before we answer, which can add a few seconds. POST /api/v1/refresh forces it. Platforms revise recent days for a while, so re-read the last two or three days when you copy data elsewhere.

Errors

Errors have an HTTP status and a body like { "error": { "code": "invalid_request", "message": "…" } }.

400invalid_requestA parameter is missing, unknown or out of range. The message says which; issues lists each one.
401unauthorizedNo key was sent, or the key is unknown or revoked.
404not_foundThere is no endpoint at that path.
405method_not_allowedWrong HTTP method. Reports are GET; refresh is POST.
500internal_errorSomething failed on our side. We are notified automatically; retry in a moment.

Limits

Lists return at most 500 rows (limit); truncated tells you when there were more. Please keep to about one request per second per key: the data changes at most a few times an hour, so polling faster only returns the same numbers. If you need more, write to support@revpanel.co.

MCP server

The same reports are available to AI assistants such as Claude, ChatGPT, Grok, Cursor and Codex as an MCP server at https://revpanel.co/mcp. The assistant picks the right report for each question and answers with the numbers we computed.

One-click sign-in. Add https://revpanel.co/mcp as a connector in your AI app. It opens a RevPanel sign-in where you approve read-only access, to all projects or one. This uses OAuth 2.1 with PKCE and dynamic client registration, as the MCP specification describes; discovery starts at /.well-known/oauth-protected-resource. Connected apps are listed under Connect to AI, where you can disconnect them.

With an API key. For clients that can't sign in, send your key as a Bearer token. For clients that take a JSON configuration:

{
  "mcpServers": {
    "revpanel": {
      "type": "http",
      "url": "https://revpanel.co/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Guide: ad spend in Mixpanel

Mixpanel can chart ad spend next to the revenue you already track, once the spend is imported as Ad Data events. This script copies spend per campaign per day from every connected platform. In Mixpanel, chart the sum of cost on Ad Data against the sum of revenue on your purchase event, and divide one by the other for return on ad spend.

import { createHash } from "node:crypto";

// Run once a night (n8n, a cron job, a serverless function).
// Re-sends the last 2 days, because platforms revise yesterday's numbers.
const since = new Date(Date.now() - 2 * 86_400_000).toISOString().slice(0, 10);

const report = await fetch(
  `https://revpanel.co/api/v1/performance?since=${since}&group_by=day,platform,campaign&limit=500`,
  { headers: { Authorization: `Bearer ${process.env.REVPANEL_API_KEY}` } },
).then((r) => r.json());

// One Mixpanel "Ad Data" event per campaign per day. The same day and
// campaign always get the same insert id, so re-sending is not counted twice.
const insertId = (row) => createHash("md5").update(`${row.platform}|${row.day}|${row.campaign}`).digest("hex");

const events = report.rows.map((row) => ({
  event: "Ad Data",
  properties: {
    time: Date.parse(`${row.day}T12:00:00Z`),
    distinct_id: "",
    $insert_id: insertId(row),
    source: row.platform,
    utm_campaign: row.campaign,
    cost: row.spend,
    currency: row.currency,
    impressions: row.impressions,
    clicks: row.clicks,
  },
}));

await fetch("https://api.mixpanel.com/import?strict=1", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Basic " + Buffer.from(`${process.env.MIXPANEL_SERVICE_ACCOUNT}:${process.env.MIXPANEL_SECRET}`).toString("base64"),
  },
  body: JSON.stringify(events),
});

Use a Mixpanel service account with access to the project. Spend stays in each account's currency, so keep currency as a property and filter or break down by it.

Endpoints

Reports are GET requests with their arguments in the query string. Lists can be comma-separated or repeated.

List projects

GET/api/v1/projects· MCP tool list_projects

The user's projects (products), the rules that assign campaigns to each, and how many campaigns are unassigned. Each project has its own conversion event (what counts as a result: purchases, leads, sign-ups...), the numbers it cares about most (keyMetrics), and an optional monthly goal with this month's progress and pace. Judge each project by its own event and key metrics, not by one metric for all.

No parameters.

curl "https://revpanel.co/api/v1/projects" \
  -H "Authorization: Bearer $REVPANEL_API_KEY"

List ad accounts

GET/api/v1/accounts· MCP tool list_accounts

Connected ad accounts with platform, currency, time zone and connection status.

No parameters.

curl "https://revpanel.co/api/v1/accounts" \
  -H "Authorization: Bearer $REVPANEL_API_KEY"

Get performance

GET/api/v1/performance· MCP tool get_performance

Advertising totals for a period (spend, impressions, clicks, conversions, CTR, CPC, CPM, CPA, ROAS), optionally broken down by project, platform, account, campaign, ad set, ad or day, and optionally with extra events such as leads, adds to cart or video views. Use for questions like 'how much did I spend on X last week', 'which ad has the best cost per purchase' or 'where does my funnel drop off'.

ParameterTypeDescription
date_presettoday | yesterday | last_7d | last_14d | last_30d | last_90d | this_month | last_monthNamed period. last_Nd presets are N complete days ending yesterday. Default: last_7d.
sincedate (YYYY-MM-DD)Start date YYYY-MM-DD (inclusive). Overrides date_preset.
untildate (YYYY-MM-DD)End date YYYY-MM-DD (inclusive). Defaults to today when since is given.
include_todaybooleanWith a last_Nd preset, end on today's partial day instead of yesterday.
projectstringProject name or id, or "unassigned".
platformmeta | google_ads | tiktok
campaignstringOnly campaigns whose name contains this text (case-insensitive).
adstringOnly ads whose name contains this text (case-insensitive).
conversion_eventstringCount this event as conversions (and for CPA, ROAS, conversion rate) instead of each project's own setting. For example lead.
eventslist of string (comma-separated)Extra events to report for every row, each with count, value, cost per event and rate per impression. Use for funnels and video. Standard events: purchase, lead, complete_registration, start_trial, subscribe, contact, schedule, submit_application, app_install, link_click, landing_page_view, view_content, search, add_to_cart, initiate_checkout, add_payment_info, post_engagement, video_play, video_view, thruplay, video_p25, video_p50, video_p75, video_p100. Custom conversions look like custom:<id>.
group_bylist of project | platform | account | campaign | ad_set | ad | day (comma-separated)Break the totals down by up to three dimensions. Omit for totals only. reach and frequency are filled only when a row is one campaign, ad set or ad on one day.
limitinteger 1–500Maximum rows, highest spend first. Default 50.
curl "https://revpanel.co/api/v1/performance?date_preset=last_7d&group_by=day,platform" \
  -H "Authorization: Bearer $REVPANEL_API_KEY"

Get breakdown

GET/api/v1/breakdown· MCP tool get_breakdown

Performance split by audience or delivery: age, gender, age_gender, country, platform (Facebook, Instagram...), placement (feed, reels, stories...) or device. For Google Ads also search_term (what people typed into Google before clicking an ad) and keyword (the advertiser's keywords that matched), each with its match type. Each row has the usual metrics plus its share of spend. Use for 'who is buying', 'does Instagram or Facebook work better', 'which placement wastes money', 'which Google searches am I paying for' or 'which keywords bring purchases'. Optionally for one campaign or ad, or split by campaign or ad (search terms and keywords: by campaign only).

ParameterTypeDescription
breakdownrequiredage | gender | age_gender | country | platform | placement | device | search_term | keywordWhat to split by.
date_presettoday | yesterday | last_7d | last_14d | last_30d | last_90d | this_month | last_monthNamed period. last_Nd presets are N complete days ending yesterday. Default: last_7d.
sincedate (YYYY-MM-DD)Start date YYYY-MM-DD (inclusive). Overrides date_preset.
untildate (YYYY-MM-DD)End date YYYY-MM-DD (inclusive). Defaults to today when since is given.
include_todaybooleanWith a last_Nd preset, end on today's partial day instead of yesterday.
projectstringProject name or id, or "unassigned".
platformmeta | google_ads | tiktok
campaignstringOnly campaigns whose name contains this text (case-insensitive).
adstringOnly ads whose name contains this text (case-insensitive).
conversion_eventstringCount this event as conversions (and for CPA, ROAS, conversion rate) instead of each project's own setting. For example lead.
eventslist of string (comma-separated)Extra events to report for every row.
split_bycampaign | adAlso split every slice by campaign or by ad. search_term and keyword split by campaign only.
termstringsearch_term and keyword only: keep those containing this text (case-insensitive).
limitinteger 1–500Maximum rows, highest spend first. Default 50.
curl "https://revpanel.co/api/v1/breakdown?breakdown=country&date_preset=last_30d" \
  -H "Authorization: Bearer $REVPANEL_API_KEY"

Compare projects

GET/api/v1/compare-projects· MCP tool compare_projects

The portfolio view: every project side by side for a period, each metric with its value in the previous period of equal length and the change. Use for 'how are my products doing' or 'which product is getting more expensive'.

ParameterTypeDescription
date_presettoday | yesterday | last_7d | last_14d | last_30d | last_90d | this_month | last_monthNamed period. last_Nd presets are N complete days ending yesterday. Default: last_7d.
sincedate (YYYY-MM-DD)Start date YYYY-MM-DD (inclusive). Overrides date_preset.
untildate (YYYY-MM-DD)End date YYYY-MM-DD (inclusive). Defaults to today when since is given.
include_todaybooleanWith a last_Nd preset, end on today's partial day instead of yesterday.
conversion_eventstringCount this event as conversions (and for CPA, ROAS, conversion rate) instead of each project's own setting. For example lead.
curl "https://revpanel.co/api/v1/compare-projects?date_preset=last_30d" \
  -H "Authorization: Bearer $REVPANEL_API_KEY"

Compare periods

GET/api/v1/compare-periods· MCP tool compare_periods

Totals for a period against the previous period of equal length, with absolute and percentage change per metric. Optionally for one project or platform.

ParameterTypeDescription
date_presettoday | yesterday | last_7d | last_14d | last_30d | last_90d | this_month | last_monthNamed period. last_Nd presets are N complete days ending yesterday. Default: last_7d.
sincedate (YYYY-MM-DD)Start date YYYY-MM-DD (inclusive). Overrides date_preset.
untildate (YYYY-MM-DD)End date YYYY-MM-DD (inclusive). Defaults to today when since is given.
include_todaybooleanWith a last_Nd preset, end on today's partial day instead of yesterday.
projectstringProject name or id, or "unassigned".
platformmeta | google_ads | tiktok
campaignstringOnly campaigns whose name contains this text (case-insensitive).
adstringOnly ads whose name contains this text (case-insensitive).
conversion_eventstringCount this event as conversions (and for CPA, ROAS, conversion rate) instead of each project's own setting. For example lead.
curl "https://revpanel.co/api/v1/compare-periods?date_preset=last_7d&project=My+Shop" \
  -H "Authorization: Bearer $REVPANEL_API_KEY"

Top movers

GET/api/v1/top-movers· MCP tool top_movers

What changed most against the previous period of equal length: campaigns, ad sets, ads, projects, platforms or accounts ranked by the absolute change in one metric. Use for 'what changed' or 'why did spend go up'.

ParameterTypeDescription
date_presettoday | yesterday | last_7d | last_14d | last_30d | last_90d | this_month | last_monthNamed period. last_Nd presets are N complete days ending yesterday. Default: last_7d.
sincedate (YYYY-MM-DD)Start date YYYY-MM-DD (inclusive). Overrides date_preset.
untildate (YYYY-MM-DD)End date YYYY-MM-DD (inclusive). Defaults to today when since is given.
include_todaybooleanWith a last_Nd preset, end on today's partial day instead of yesterday.
projectstringProject name or id, or "unassigned".
platformmeta | google_ads | tiktok
campaignstringOnly campaigns whose name contains this text (case-insensitive).
adstringOnly ads whose name contains this text (case-insensitive).
conversion_eventstringCount this event as conversions (and for CPA, ROAS, conversion rate) instead of each project's own setting. For example lead.
dimensioncampaign | ad_set | ad | project | platform | accountWhat to rank. Default: campaign.
metricspend | impressions | clicks | conversions | conversionValue | ctr | cpc | cpm | cpa | roas | conversionRateMetric to rank by. Default: spend.
limitinteger 1–50Default 10.
curl "https://revpanel.co/api/v1/top-movers?date_preset=last_7d&metric=spend" \
  -H "Authorization: Bearer $REVPANEL_API_KEY"

List events

GET/api/v1/events· MCP tool list_events

The conversion, funnel and video events the connected ad accounts actually reported in a period (default last 30 days), with counts and values. Call this before asking for events, and to find out what a project could use as its conversion event.

ParameterTypeDescription
date_presettoday | yesterday | last_7d | last_14d | last_30d | last_90d | this_month | last_monthNamed period. last_Nd presets are N complete days ending yesterday. Default: last_7d.
sincedate (YYYY-MM-DD)Start date YYYY-MM-DD (inclusive). Overrides date_preset.
untildate (YYYY-MM-DD)End date YYYY-MM-DD (inclusive). Defaults to today when since is given.
include_todaybooleanWith a last_Nd preset, end on today's partial day instead of yesterday.
projectstringProject name or id, or "unassigned".
platformmeta | google_ads | tiktok
campaignstringOnly campaigns whose name contains this text (case-insensitive).
adstringOnly ads whose name contains this text (case-insensitive).
curl "https://revpanel.co/api/v1/events?date_preset=last_30d" \
  -H "Authorization: Bearer $REVPANEL_API_KEY"

List fields

GET/api/v1/fields· MCP tool list_fields

Definitions of every metric, dimension and standard event, including how each ratio is computed.

No parameters.

curl "https://revpanel.co/api/v1/fields" \
  -H "Authorization: Bearer $REVPANEL_API_KEY"

Sync status

GET/api/v1/sync-status· MCP tool sync_status

How fresh the data is: last successful sync, the dates covered and any current problem, per ad account. Check this when numbers look stale or missing.

No parameters.

curl "https://revpanel.co/api/v1/sync-status" \
  -H "Authorization: Bearer $REVPANEL_API_KEY"

Refresh data now

POST/api/v1/refresh· MCP tool refresh_data

Pull the latest numbers from the ad platforms and Google Analytics right away (today and yesterday), instead of waiting for the next scheduled sync. Reports already refresh data older than an hour on their own; use this when the user asks for the very latest figures or says the numbers look stale.

No parameters.

curl -X POST "https://revpanel.co/api/v1/refresh" \
  -H "Authorization: Bearer $REVPANEL_API_KEY"

List sites and Analytics properties

GET/api/v1/web-properties· MCP tool list_web_properties

Connected Google Search Console sites and Google Analytics 4 properties, the project each belongs to, and how recent their data is.

No parameters.

curl "https://revpanel.co/api/v1/web-properties" \
  -H "Authorization: Bearer $REVPANEL_API_KEY"

Organic search performance

GET/api/v1/search-performance· MCP tool get_search_performance

Unpaid Google Search results from Search Console: clicks, impressions, CTR and average position (1 = top). Group by day, query, page, site or project. Totals include anonymised queries; a split by query or page does not, so it adds up to less. Data is about 2 days behind. Default period: last 30 days.

ParameterTypeDescription
date_presettoday | yesterday | last_7d | last_14d | last_30d | last_90d | this_month | last_monthNamed period. last_Nd presets are N complete days ending yesterday. Default: last_7d.
sincedate (YYYY-MM-DD)Start date YYYY-MM-DD (inclusive). Overrides date_preset.
untildate (YYYY-MM-DD)End date YYYY-MM-DD (inclusive). Defaults to today when since is given.
projectstringProject name or id.
sitestringSite as shown by list_web_properties, e.g. sc-domain:example.com.
group_byday | query | page | site | project
querystringOnly search queries containing this text.
limitinteger 1–500
curl "https://revpanel.co/api/v1/search-performance?date_preset=last_30d&group_by=query&limit=20" \
  -H "Authorization: Bearer $REVPANEL_API_KEY"

Website traffic

GET/api/v1/site-traffic· MCP tool get_site_traffic

Website sessions from Google Analytics 4 by day, channel (Organic Search, Paid Social, Direct...), source / medium, property or project: sessions, engaged sessions, engagement rate, new users, key events and revenue (in each property's currency). Default period: last 7 days.

ParameterTypeDescription
date_presettoday | yesterday | last_7d | last_14d | last_30d | last_90d | this_month | last_monthNamed period. last_Nd presets are N complete days ending yesterday. Default: last_7d.
sincedate (YYYY-MM-DD)Start date YYYY-MM-DD (inclusive). Overrides date_preset.
untildate (YYYY-MM-DD)End date YYYY-MM-DD (inclusive). Defaults to today when since is given.
projectstringProject name or id.
propertystringGA4 property id or name, as shown by list_web_properties.
channelstringOnly one channel, e.g. "Organic Search".
group_byday | channel | source_medium | property | project
limitinteger 1–500
curl "https://revpanel.co/api/v1/site-traffic?date_preset=last_7d&group_by=channel" \
  -H "Authorization: Bearer $REVPANEL_API_KEY"