{"openapi":"3.1.0","info":{"title":"RevPanel API","version":"1.0.0","description":"Read-only advertising, search and analytics data organized by project. The same reports as the RevPanel MCP server. Docs: https://revpanel.co/docs/api"},"servers":[{"url":"https://revpanel.co"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"An API key from RevPanel → Connect to AI. Keys start with sc_live_."}},"responses":{"Error":{"description":"An error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","not_found","method_not_allowed","invalid_request","internal_error"]},"message":{"type":"string"}},"required":["code","message"]}}}}}}}},"paths":{"/api/v1/projects":{"get":{"operationId":"list_projects","summary":"List projects","description":"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.","parameters":[],"responses":{"200":{"description":"The report. Results carry a `meta` block with the exact dates, time zones, currencies and any warnings.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/api/v1/accounts":{"get":{"operationId":"list_accounts","summary":"List ad accounts","description":"Connected ad accounts with platform, currency, time zone and connection status.","parameters":[],"responses":{"200":{"description":"The report. Results carry a `meta` block with the exact dates, time zones, currencies and any warnings.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/api/v1/performance":{"get":{"operationId":"get_performance","summary":"Get performance","description":"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'.","parameters":[{"name":"date_preset","in":"query","required":false,"description":"Named period. last_Nd presets are N complete days ending yesterday. Default: last_7d.","schema":{"type":"string","enum":["today","yesterday","last_7d","last_14d","last_30d","last_90d","this_month","last_month"]}},{"name":"since","in":"query","required":false,"description":"Start date YYYY-MM-DD (inclusive). Overrides date_preset.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"until","in":"query","required":false,"description":"End date YYYY-MM-DD (inclusive). Defaults to today when since is given.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"include_today","in":"query","required":false,"description":"With a last_Nd preset, end on today's partial day instead of yesterday.","schema":{"type":"boolean"}},{"name":"project","in":"query","required":false,"description":"Project name or id, or \"unassigned\".","schema":{"type":"string"}},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["meta","google_ads","tiktok"]}},{"name":"campaign","in":"query","required":false,"description":"Only campaigns whose name contains this text (case-insensitive).","schema":{"type":"string","maxLength":200}},{"name":"ad","in":"query","required":false,"description":"Only ads whose name contains this text (case-insensitive).","schema":{"type":"string","maxLength":200}},{"name":"conversion_event","in":"query","required":false,"description":"Count this event as conversions (and for CPA, ROAS, conversion rate) instead of each project's own setting. For example lead.","schema":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,140}$"}},{"name":"events","in":"query","required":false,"description":"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>.","schema":{"maxItems":12,"type":"array","items":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,140}$"}},"style":"form","explode":false},{"name":"group_by","in":"query","required":false,"description":"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.","schema":{"maxItems":3,"type":"array","items":{"type":"string","enum":["project","platform","account","campaign","ad_set","ad","day"]}},"style":"form","explode":false},{"name":"limit","in":"query","required":false,"description":"Maximum rows, highest spend first. Default 50.","schema":{"type":"integer","minimum":1,"maximum":500}}],"responses":{"200":{"description":"The report. Results carry a `meta` block with the exact dates, time zones, currencies and any warnings.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/api/v1/breakdown":{"get":{"operationId":"get_breakdown","summary":"Get breakdown","description":"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).","parameters":[{"name":"breakdown","in":"query","required":true,"description":"What to split by.","schema":{"type":"string","enum":["age","gender","age_gender","country","platform","placement","device","search_term","keyword"]}},{"name":"date_preset","in":"query","required":false,"description":"Named period. last_Nd presets are N complete days ending yesterday. Default: last_7d.","schema":{"type":"string","enum":["today","yesterday","last_7d","last_14d","last_30d","last_90d","this_month","last_month"]}},{"name":"since","in":"query","required":false,"description":"Start date YYYY-MM-DD (inclusive). Overrides date_preset.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"until","in":"query","required":false,"description":"End date YYYY-MM-DD (inclusive). Defaults to today when since is given.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"include_today","in":"query","required":false,"description":"With a last_Nd preset, end on today's partial day instead of yesterday.","schema":{"type":"boolean"}},{"name":"project","in":"query","required":false,"description":"Project name or id, or \"unassigned\".","schema":{"type":"string"}},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["meta","google_ads","tiktok"]}},{"name":"campaign","in":"query","required":false,"description":"Only campaigns whose name contains this text (case-insensitive).","schema":{"type":"string","maxLength":200}},{"name":"ad","in":"query","required":false,"description":"Only ads whose name contains this text (case-insensitive).","schema":{"type":"string","maxLength":200}},{"name":"conversion_event","in":"query","required":false,"description":"Count this event as conversions (and for CPA, ROAS, conversion rate) instead of each project's own setting. For example lead.","schema":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,140}$"}},{"name":"events","in":"query","required":false,"description":"Extra events to report for every row.","schema":{"maxItems":12,"type":"array","items":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,140}$"}},"style":"form","explode":false},{"name":"split_by","in":"query","required":false,"description":"Also split every slice by campaign or by ad. search_term and keyword split by campaign only.","schema":{"type":"string","enum":["campaign","ad"]}},{"name":"term","in":"query","required":false,"description":"search_term and keyword only: keep those containing this text (case-insensitive).","schema":{"type":"string","maxLength":200}},{"name":"limit","in":"query","required":false,"description":"Maximum rows, highest spend first. Default 50.","schema":{"type":"integer","minimum":1,"maximum":500}}],"responses":{"200":{"description":"The report. Results carry a `meta` block with the exact dates, time zones, currencies and any warnings.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/api/v1/compare-projects":{"get":{"operationId":"compare_projects","summary":"Compare projects","description":"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'.","parameters":[{"name":"date_preset","in":"query","required":false,"description":"Named period. last_Nd presets are N complete days ending yesterday. Default: last_7d.","schema":{"type":"string","enum":["today","yesterday","last_7d","last_14d","last_30d","last_90d","this_month","last_month"]}},{"name":"since","in":"query","required":false,"description":"Start date YYYY-MM-DD (inclusive). Overrides date_preset.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"until","in":"query","required":false,"description":"End date YYYY-MM-DD (inclusive). Defaults to today when since is given.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"include_today","in":"query","required":false,"description":"With a last_Nd preset, end on today's partial day instead of yesterday.","schema":{"type":"boolean"}},{"name":"conversion_event","in":"query","required":false,"description":"Count this event as conversions (and for CPA, ROAS, conversion rate) instead of each project's own setting. For example lead.","schema":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,140}$"}}],"responses":{"200":{"description":"The report. Results carry a `meta` block with the exact dates, time zones, currencies and any warnings.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/api/v1/compare-periods":{"get":{"operationId":"compare_periods","summary":"Compare periods","description":"Totals for a period against the previous period of equal length, with absolute and percentage change per metric. Optionally for one project or platform.","parameters":[{"name":"date_preset","in":"query","required":false,"description":"Named period. last_Nd presets are N complete days ending yesterday. Default: last_7d.","schema":{"type":"string","enum":["today","yesterday","last_7d","last_14d","last_30d","last_90d","this_month","last_month"]}},{"name":"since","in":"query","required":false,"description":"Start date YYYY-MM-DD (inclusive). Overrides date_preset.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"until","in":"query","required":false,"description":"End date YYYY-MM-DD (inclusive). Defaults to today when since is given.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"include_today","in":"query","required":false,"description":"With a last_Nd preset, end on today's partial day instead of yesterday.","schema":{"type":"boolean"}},{"name":"project","in":"query","required":false,"description":"Project name or id, or \"unassigned\".","schema":{"type":"string"}},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["meta","google_ads","tiktok"]}},{"name":"campaign","in":"query","required":false,"description":"Only campaigns whose name contains this text (case-insensitive).","schema":{"type":"string","maxLength":200}},{"name":"ad","in":"query","required":false,"description":"Only ads whose name contains this text (case-insensitive).","schema":{"type":"string","maxLength":200}},{"name":"conversion_event","in":"query","required":false,"description":"Count this event as conversions (and for CPA, ROAS, conversion rate) instead of each project's own setting. For example lead.","schema":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,140}$"}}],"responses":{"200":{"description":"The report. Results carry a `meta` block with the exact dates, time zones, currencies and any warnings.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/api/v1/top-movers":{"get":{"operationId":"top_movers","summary":"Top movers","description":"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'.","parameters":[{"name":"date_preset","in":"query","required":false,"description":"Named period. last_Nd presets are N complete days ending yesterday. Default: last_7d.","schema":{"type":"string","enum":["today","yesterday","last_7d","last_14d","last_30d","last_90d","this_month","last_month"]}},{"name":"since","in":"query","required":false,"description":"Start date YYYY-MM-DD (inclusive). Overrides date_preset.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"until","in":"query","required":false,"description":"End date YYYY-MM-DD (inclusive). Defaults to today when since is given.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"include_today","in":"query","required":false,"description":"With a last_Nd preset, end on today's partial day instead of yesterday.","schema":{"type":"boolean"}},{"name":"project","in":"query","required":false,"description":"Project name or id, or \"unassigned\".","schema":{"type":"string"}},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["meta","google_ads","tiktok"]}},{"name":"campaign","in":"query","required":false,"description":"Only campaigns whose name contains this text (case-insensitive).","schema":{"type":"string","maxLength":200}},{"name":"ad","in":"query","required":false,"description":"Only ads whose name contains this text (case-insensitive).","schema":{"type":"string","maxLength":200}},{"name":"conversion_event","in":"query","required":false,"description":"Count this event as conversions (and for CPA, ROAS, conversion rate) instead of each project's own setting. For example lead.","schema":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,140}$"}},{"name":"dimension","in":"query","required":false,"description":"What to rank. Default: campaign.","schema":{"type":"string","enum":["campaign","ad_set","ad","project","platform","account"]}},{"name":"metric","in":"query","required":false,"description":"Metric to rank by. Default: spend.","schema":{"type":"string","enum":["spend","impressions","clicks","conversions","conversionValue","ctr","cpc","cpm","cpa","roas","conversionRate"]}},{"name":"limit","in":"query","required":false,"description":"Default 10.","schema":{"type":"integer","minimum":1,"maximum":50}}],"responses":{"200":{"description":"The report. Results carry a `meta` block with the exact dates, time zones, currencies and any warnings.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/api/v1/events":{"get":{"operationId":"list_events","summary":"List events","description":"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.","parameters":[{"name":"date_preset","in":"query","required":false,"description":"Named period. last_Nd presets are N complete days ending yesterday. Default: last_7d.","schema":{"type":"string","enum":["today","yesterday","last_7d","last_14d","last_30d","last_90d","this_month","last_month"]}},{"name":"since","in":"query","required":false,"description":"Start date YYYY-MM-DD (inclusive). Overrides date_preset.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"until","in":"query","required":false,"description":"End date YYYY-MM-DD (inclusive). Defaults to today when since is given.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"include_today","in":"query","required":false,"description":"With a last_Nd preset, end on today's partial day instead of yesterday.","schema":{"type":"boolean"}},{"name":"project","in":"query","required":false,"description":"Project name or id, or \"unassigned\".","schema":{"type":"string"}},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["meta","google_ads","tiktok"]}},{"name":"campaign","in":"query","required":false,"description":"Only campaigns whose name contains this text (case-insensitive).","schema":{"type":"string","maxLength":200}},{"name":"ad","in":"query","required":false,"description":"Only ads whose name contains this text (case-insensitive).","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"The report. Results carry a `meta` block with the exact dates, time zones, currencies and any warnings.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/api/v1/fields":{"get":{"operationId":"list_fields","summary":"List fields","description":"Definitions of every metric, dimension and standard event, including how each ratio is computed.","parameters":[],"responses":{"200":{"description":"The report. Results carry a `meta` block with the exact dates, time zones, currencies and any warnings.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/api/v1/sync-status":{"get":{"operationId":"sync_status","summary":"Sync status","description":"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.","parameters":[],"responses":{"200":{"description":"The report. Results carry a `meta` block with the exact dates, time zones, currencies and any warnings.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/api/v1/refresh":{"post":{"operationId":"refresh_data","summary":"Refresh data now","description":"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.","parameters":[],"responses":{"200":{"description":"The report. Results carry a `meta` block with the exact dates, time zones, currencies and any warnings.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/api/v1/web-properties":{"get":{"operationId":"list_web_properties","summary":"List sites and Analytics properties","description":"Connected Google Search Console sites and Google Analytics 4 properties, the project each belongs to, and how recent their data is.","parameters":[],"responses":{"200":{"description":"The report. Results carry a `meta` block with the exact dates, time zones, currencies and any warnings.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/api/v1/search-performance":{"get":{"operationId":"get_search_performance","summary":"Organic search performance","description":"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.","parameters":[{"name":"date_preset","in":"query","required":false,"description":"Named period. last_Nd presets are N complete days ending yesterday. Default: last_7d.","schema":{"type":"string","enum":["today","yesterday","last_7d","last_14d","last_30d","last_90d","this_month","last_month"]}},{"name":"since","in":"query","required":false,"description":"Start date YYYY-MM-DD (inclusive). Overrides date_preset.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"until","in":"query","required":false,"description":"End date YYYY-MM-DD (inclusive). Defaults to today when since is given.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"project","in":"query","required":false,"description":"Project name or id.","schema":{"type":"string"}},{"name":"site","in":"query","required":false,"description":"Site as shown by list_web_properties, e.g. sc-domain:example.com.","schema":{"type":"string"}},{"name":"group_by","in":"query","required":false,"schema":{"type":"string","enum":["day","query","page","site","project"]}},{"name":"query","in":"query","required":false,"description":"Only search queries containing this text.","schema":{"type":"string","maxLength":200}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500}}],"responses":{"200":{"description":"The report. Results carry a `meta` block with the exact dates, time zones, currencies and any warnings.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/api/v1/site-traffic":{"get":{"operationId":"get_site_traffic","summary":"Website traffic","description":"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.","parameters":[{"name":"date_preset","in":"query","required":false,"description":"Named period. last_Nd presets are N complete days ending yesterday. Default: last_7d.","schema":{"type":"string","enum":["today","yesterday","last_7d","last_14d","last_30d","last_90d","this_month","last_month"]}},{"name":"since","in":"query","required":false,"description":"Start date YYYY-MM-DD (inclusive). Overrides date_preset.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"until","in":"query","required":false,"description":"End date YYYY-MM-DD (inclusive). Defaults to today when since is given.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"project","in":"query","required":false,"description":"Project name or id.","schema":{"type":"string"}},{"name":"property","in":"query","required":false,"description":"GA4 property id or name, as shown by list_web_properties.","schema":{"type":"string"}},{"name":"channel","in":"query","required":false,"description":"Only one channel, e.g. \"Organic Search\".","schema":{"type":"string","maxLength":100}},{"name":"group_by","in":"query","required":false,"schema":{"type":"string","enum":["day","channel","source_medium","property","project"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500}}],"responses":{"200":{"description":"The report. Results carry a `meta` block with the exact dates, time zones, currencies and any warnings.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}}}}