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
- Sign in to RevPanel and connect your ad accounts under Connections.
- 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.
- 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 examplelast_7d, which is the 7 complete days ending yesterday) or withsinceanduntil(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
metablock with the exact dates, time zones, currencies andwarnings, 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/refreshforces 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": "…" } }.
| 400 | invalid_request | A parameter is missing, unknown or out of range. The message says which; issues lists each one. |
| 401 | unauthorized | No key was sent, or the key is unknown or revoked. |
| 404 | not_found | There is no endpoint at that path. |
| 405 | method_not_allowed | Wrong HTTP method. Reports are GET; refresh is POST. |
| 500 | internal_error | Something 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'.
| Parameter | Type | Description |
|---|---|---|
| date_preset | today | yesterday | last_7d | last_14d | last_30d | last_90d | this_month | last_month | Named period. last_Nd presets are N complete days ending yesterday. Default: last_7d. |
| since | date (YYYY-MM-DD) | Start date YYYY-MM-DD (inclusive). Overrides date_preset. |
| until | date (YYYY-MM-DD) | End date YYYY-MM-DD (inclusive). Defaults to today when since is given. |
| include_today | boolean | With a last_Nd preset, end on today's partial day instead of yesterday. |
| project | string | Project name or id, or "unassigned". |
| platform | meta | google_ads | tiktok | |
| campaign | string | Only campaigns whose name contains this text (case-insensitive). |
| ad | string | Only ads whose name contains this text (case-insensitive). |
| conversion_event | string | Count this event as conversions (and for CPA, ROAS, conversion rate) instead of each project's own setting. For example lead. |
| events | list 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_by | list 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. |
| limit | integer 1–500 | Maximum 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).
| Parameter | Type | Description |
|---|---|---|
| breakdownrequired | age | gender | age_gender | country | platform | placement | device | search_term | keyword | What to split by. |
| date_preset | today | yesterday | last_7d | last_14d | last_30d | last_90d | this_month | last_month | Named period. last_Nd presets are N complete days ending yesterday. Default: last_7d. |
| since | date (YYYY-MM-DD) | Start date YYYY-MM-DD (inclusive). Overrides date_preset. |
| until | date (YYYY-MM-DD) | End date YYYY-MM-DD (inclusive). Defaults to today when since is given. |
| include_today | boolean | With a last_Nd preset, end on today's partial day instead of yesterday. |
| project | string | Project name or id, or "unassigned". |
| platform | meta | google_ads | tiktok | |
| campaign | string | Only campaigns whose name contains this text (case-insensitive). |
| ad | string | Only ads whose name contains this text (case-insensitive). |
| conversion_event | string | Count this event as conversions (and for CPA, ROAS, conversion rate) instead of each project's own setting. For example lead. |
| events | list of string (comma-separated) | Extra events to report for every row. |
| split_by | campaign | ad | Also split every slice by campaign or by ad. search_term and keyword split by campaign only. |
| term | string | search_term and keyword only: keep those containing this text (case-insensitive). |
| limit | integer 1–500 | Maximum 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'.
| Parameter | Type | Description |
|---|---|---|
| date_preset | today | yesterday | last_7d | last_14d | last_30d | last_90d | this_month | last_month | Named period. last_Nd presets are N complete days ending yesterday. Default: last_7d. |
| since | date (YYYY-MM-DD) | Start date YYYY-MM-DD (inclusive). Overrides date_preset. |
| until | date (YYYY-MM-DD) | End date YYYY-MM-DD (inclusive). Defaults to today when since is given. |
| include_today | boolean | With a last_Nd preset, end on today's partial day instead of yesterday. |
| conversion_event | string | Count 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.
| Parameter | Type | Description |
|---|---|---|
| date_preset | today | yesterday | last_7d | last_14d | last_30d | last_90d | this_month | last_month | Named period. last_Nd presets are N complete days ending yesterday. Default: last_7d. |
| since | date (YYYY-MM-DD) | Start date YYYY-MM-DD (inclusive). Overrides date_preset. |
| until | date (YYYY-MM-DD) | End date YYYY-MM-DD (inclusive). Defaults to today when since is given. |
| include_today | boolean | With a last_Nd preset, end on today's partial day instead of yesterday. |
| project | string | Project name or id, or "unassigned". |
| platform | meta | google_ads | tiktok | |
| campaign | string | Only campaigns whose name contains this text (case-insensitive). |
| ad | string | Only ads whose name contains this text (case-insensitive). |
| conversion_event | string | Count 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'.
| Parameter | Type | Description |
|---|---|---|
| date_preset | today | yesterday | last_7d | last_14d | last_30d | last_90d | this_month | last_month | Named period. last_Nd presets are N complete days ending yesterday. Default: last_7d. |
| since | date (YYYY-MM-DD) | Start date YYYY-MM-DD (inclusive). Overrides date_preset. |
| until | date (YYYY-MM-DD) | End date YYYY-MM-DD (inclusive). Defaults to today when since is given. |
| include_today | boolean | With a last_Nd preset, end on today's partial day instead of yesterday. |
| project | string | Project name or id, or "unassigned". |
| platform | meta | google_ads | tiktok | |
| campaign | string | Only campaigns whose name contains this text (case-insensitive). |
| ad | string | Only ads whose name contains this text (case-insensitive). |
| conversion_event | string | Count this event as conversions (and for CPA, ROAS, conversion rate) instead of each project's own setting. For example lead. |
| dimension | campaign | ad_set | ad | project | platform | account | What to rank. Default: campaign. |
| metric | spend | impressions | clicks | conversions | conversionValue | ctr | cpc | cpm | cpa | roas | conversionRate | Metric to rank by. Default: spend. |
| limit | integer 1–50 | Default 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.
| Parameter | Type | Description |
|---|---|---|
| date_preset | today | yesterday | last_7d | last_14d | last_30d | last_90d | this_month | last_month | Named period. last_Nd presets are N complete days ending yesterday. Default: last_7d. |
| since | date (YYYY-MM-DD) | Start date YYYY-MM-DD (inclusive). Overrides date_preset. |
| until | date (YYYY-MM-DD) | End date YYYY-MM-DD (inclusive). Defaults to today when since is given. |
| include_today | boolean | With a last_Nd preset, end on today's partial day instead of yesterday. |
| project | string | Project name or id, or "unassigned". |
| platform | meta | google_ads | tiktok | |
| campaign | string | Only campaigns whose name contains this text (case-insensitive). |
| ad | string | Only 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.
| Parameter | Type | Description |
|---|---|---|
| date_preset | today | yesterday | last_7d | last_14d | last_30d | last_90d | this_month | last_month | Named period. last_Nd presets are N complete days ending yesterday. Default: last_7d. |
| since | date (YYYY-MM-DD) | Start date YYYY-MM-DD (inclusive). Overrides date_preset. |
| until | date (YYYY-MM-DD) | End date YYYY-MM-DD (inclusive). Defaults to today when since is given. |
| project | string | Project name or id. |
| site | string | Site as shown by list_web_properties, e.g. sc-domain:example.com. |
| group_by | day | query | page | site | project | |
| query | string | Only search queries containing this text. |
| limit | integer 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.
| Parameter | Type | Description |
|---|---|---|
| date_preset | today | yesterday | last_7d | last_14d | last_30d | last_90d | this_month | last_month | Named period. last_Nd presets are N complete days ending yesterday. Default: last_7d. |
| since | date (YYYY-MM-DD) | Start date YYYY-MM-DD (inclusive). Overrides date_preset. |
| until | date (YYYY-MM-DD) | End date YYYY-MM-DD (inclusive). Defaults to today when since is given. |
| project | string | Project name or id. |
| property | string | GA4 property id or name, as shown by list_web_properties. |
| channel | string | Only one channel, e.g. "Organic Search". |
| group_by | day | channel | source_medium | property | project | |
| limit | integer 1–500 |
curl "https://revpanel.co/api/v1/site-traffic?date_preset=last_7d&group_by=channel" \
-H "Authorization: Bearer $REVPANEL_API_KEY"