APIREST API & MCPMeta Ads
Meta Ads API. Facebook and Instagram ad figures for your own dashboard and AI.
Pull a client site's Facebook and Instagram spend, reach, link clicks, purchases, leads and ROAS straight into your own report or AI assistant. We keep the Meta connection and endpoints running in the background. Every MarketingTracer plan includes the REST API and MCP at no extra cost.
Facebook and Instagram
Totals, daily lines, campaigns, ad sets, ads, placements, devices and demographics.
Shared metric names
Spend, link clicks, CTR, CPC and ROAS use the same field names as our Google Ads API.
Purchases counted once
Each purchase, lead or cart action is counted once across Meta's action names.
In every plan
60 calls a minute on a personal key and 600 on a white-label key, at no extra cost.
Meta Ads endpoints and MCP tools
Every read endpoint in the metaads topic is available as a POST or GET call to /rest/v1/<endpoint> and as a tool in the MarketingTracer MCP server. Choosing the ad account and disconnecting are write calls in the REST API.
| REST endpoint | MCP tool | What it returns |
|---|---|---|
metaads.summary |
get_metaads_summary |
Account totals for the period against the comparison period: cost, impressions, reach, frequency, clicks (link clicks), ctr_pct, average_cpc, cpm, purchases, purchase_value, cost_per_purchase, roas, leads and cost_per_lead, each with value, previous, change and change_pct. |
metaads.daily |
get_metaads_daily |
Figures per day, oldest first, paired with the matching day of the comparison period. Reach and frequency are left out because daily reach does not add up over a period. |
metaads.campaigns |
get_metaads_campaigns |
Campaigns that had impressions in the period, most spent first: delivery status, objective (sales, leads, traffic, awareness, engagement, app_promotion), daily_budget or lifetime_budget, all metrics, share_pct of total spend, and previous. |
metaads.adsets |
get_metaads_adsets |
Ad sets that had impressions in the period, most spent first, optionally filtered by campaign_id: status, daily or lifetime budget, campaign, all metrics, cost share and previous period. |
metaads.ads |
get_metaads_ads |
Ads that had impressions in the period, most spent first, optionally filtered by campaign_id or adset_id: status, ad set, campaign, all metrics, cost share and previous period. |
metaads.placements |
get_metaads_placements |
Figures per platform (facebook, instagram, messenger, audience_network, threads), most spent first, with cost share and previous period. |
metaads.devices |
get_metaads_devices |
Figures per device (mobile for app and mobile browser together, desktop, other), most spent first, with cost share and previous period. |
metaads.demographics |
get_metaads_demographics |
Figures per age group (13-17, 18-24, 25-34, 35-44, 45-54, 55-64, 65+, unknown) and gender (female, male, unknown), most spent first. |
metaads.results |
get_metaads_results |
What people did after seeing the ads, per action (purchase, lead, complete_registration, initiate_checkout, add_payment_info, add_to_cart, view_content, search, contact, subscribe, app_install, landing_page_view, link_click, video_view, post_engagement), with count, value and cost_per_action against the previous period. |
metaads.accounts |
get_metaads_accounts |
Whether a Facebook user is connected and the connection still works, the chosen account_id, and all personal and Business Manager ad accounts that user can read. |
metaads.account_set |
REST only | Chooses which ad account from metaads.accounts the site uses (with or without act_ in front) and returns its account_id, name and currency. |
metaads.disconnect |
REST only | Disconnects the Facebook user and clears the chosen Meta ad account for the site. |
Every reporting call accepts days (1 to 366, default 28 through yesterday) or a from and to date range up to 366 days. Set compare to previous_period or previous_year (the same weekdays 52 weeks earlier, for periods up to 364 days). Amounts use the ad account's currency (meta.currency).
A call to metaads.campaigns and its answer
Pass your API key in the Authorization header and the client's site_id in the JSON body. The answer below comes from the sample running-shoe shop in our API test suite. We shortened it with …:
curl -X POST https://app.marketingtracer.com/rest/v1/metaads.campaigns \
-H "Authorization: Bearer mtk_your_api_key" \
-H "Content-Type: application/json" \
-d '{"site_id": "65a1b2c3d4e5f60718293a4b", "days": 28, "limit": 2}'
{
"data": [
{
"campaign_id": "120200000091384315",
"campaign": "Prospecting | Running shoes",
"status": "active",
"objective": "sales",
"daily_budget": 65,
"lifetime_budget": null,
"cost": 1563.66,
"impressions": 189625,
"reach": 111544,
"frequency": 1.7,
"clicks": 2088,
"ctr_pct": 1.1,
"average_cpc": 0.75,
"cpm": 8.25,
"purchases": 41,
"purchase_value": 5193.4,
"cost_per_purchase": 38.14,
"roas": 3.32,
"leads": 0,
"cost_per_lead": null,
"share_pct": 55.3,
"previous": {
"cost": 1501.54,
"impressions": 178334,
"reach": 104902,
"frequency": 1.7,
"clicks": 1935,
"ctr_pct": 1.09,
"average_cpc": 0.78,
"cpm": 8.42,
"purchases": 41,
"purchase_value": 5219.6,
"cost_per_purchase": 36.62,
"roas": 3.48,
…
}
},
{
"campaign_id": "120200000016043000",
"campaign": "Retargeting | Cart abandoners",
"status": "active",
"objective": "sales",
"daily_budget": 25,
"lifetime_budget": null,
"cost": 602.5,
"impressions": 39894,
"reach": 11082,
"frequency": 3.6,
"clicks": 984,
"ctr_pct": 2.47,
"average_cpc": 0.61,
"cpm": 15.1,
"purchases": 61,
"purchase_value": 7063.89,
"cost_per_purchase": 9.88,
"roas": 11.72,
"share_pct": 21.3,
…
}
],
"meta": {
"site_id": "65a1b2c3d4e5f60718293a4b",
"next_cursor": "2",
"total": 4,
"period": {
"from": "2026-10-17",
"to": "2026-11-13",
"compare_from": "2026-09-19",
"compare_to": "2026-10-16"
},
"currency": "EUR"
}
}
Put Meta Ads and Google Ads in one table
When a client spends on both Google Search and Instagram, they ask for one monthly overview that shows what went in and what came back. metaads uses the same field names as googleads where metrics match: cost, clicks for link clicks, ctr_pct, average_cpc and roas. Your dashboard renders both channels with the same component.
Where paid social has its own numbers, you add reach, frequency and cpm right beside them. Every row includes previous and share_pct, so period-over-period arrows and budget share bars need no extra query.
Zoom from campaign to ad set, ad and placement
When cost per purchase creeps up over the last 28 days, you want to see which audience or creative caused it. Start at metaads.campaigns, pass a campaign_id to metaads.adsets, and pass an adset_id to metaads.ads to compare every video or carousel ad against its previous 28 days.
If the creatives look steady, call metaads.placements and metaads.demographics to check whether spend shifted between Instagram, Facebook, Messenger, Audience Network and Threads, or across age and gender groups.
Count each conversion once and ask across channels in your AI
Meta reports a single shop order under several action names, such as omni_purchase, purchase and onsite_web_purchase. Summing them would count the same order three times. metaads.results picks the primary count per action. Your funnel stays accurate from link clicks and landing page views to adds to cart, checkouts started and purchases.
In Claude or ChatGPT with the SEO MCP, ask how a client's Meta campaigns performed next to their Google Ads search terms, GA4 landing pages and Search Console queries in a single conversation.
Endpoints, arguments and field descriptions
Every endpoint is a POST with a JSON body; reading endpoints also take a GET with the same arguments in the query string. Send your API key as Authorization: Bearer YOUR_API_KEY. Every answer is {"data": …, "meta": {…}}: meta.site_id always, meta.next_cursor and meta.total for a list, meta.period where the endpoint covers a period. An error is {"error": {"code", "message"}} with the HTTP status: 400 invalid_argument, unknown_argument or missing_argument; 401 not_authenticated; 403 no_access or tool_off; 404 not_found; 409 not_connected (a connection the endpoint needs, such as Google Analytics 4, is missing); 429 rate_limited; 502 google_error (Google returned an error on your own Search Console or Analytics connection) or upstream_error (another data source did not answer; try again in a minute). The machine-readable version is openapi.json.
metaads.summary
POST /rest/v1/metaads.summary · MCP tool get_metaads_summary
Returns the Meta Ads (Facebook and Instagram) totals of the chosen ad account of one site for the period against the previous period: amount spent, impressions, reach, frequency, link clicks, CTR, cost per click, CPM, purchases, purchase value, cost per purchase, ROAS, leads and cost per lead, each as value, previous, change and change in percent. Reach is the number of people in the whole period. Per day: metaads.daily. The period runs up to yesterday at the latest; meta.period gives it and the previous period, meta.currency the account currency (EUR). Fails with 409 not_connected when Meta Ads is not connected for the site (or the connection expired: Meta connections last about 60 days), 409 no_account when no ad account is chosen.
Arguments
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
from | string, YYYY-MM-DD | First day of the period, YYYY-MM-DD; give it together with to. |
to | string, YYYY-MM-DD | Last day of the period, YYYY-MM-DD (yesterday at the latest); give it together with from. At most 366 days. |
days | integer, 1 to 366, default 28 | Without from and to: the last this many days up to yesterday. Defaults to 28. |
compare | one of previous_period, previous_year | What the previous figures are: previous_period (the same number of days just before) or previous_year (the same days 52 weeks earlier, same weekdays; for periods up to 364 days). Defaults to previous_period. |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/metaads.summary \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"site_id":"YOUR_SITE_ID","days":28}'
Example response · Sample figures of a made-up web shop.
{
"data": {
"compare": "previous_period",
"cost": {"value": 2825.35, "previous": 2868.6, "change": -43.25, "change_pct": -1.5},
"impressions": {"value": 380117, "previous": 418890, "change": -38773, "change_pct": -9.3},
"reach": {"value": 157023, "previous": 169748, "change": -12725, "change_pct": -7.5},
"frequency": {"value": 2.42, "previous": 2.47, "change": -0.05, "change_pct": -2},
"clicks": {"value": 4274, "previous": 4121, "change": 153, "change_pct": 3.7},
"ctr_pct": {"value": 1.12, "previous": 0.98, "change": 0.14, "change_pct": 14.3},
"average_cpc": {"value": 0.66, "previous": 0.7, "change": -0.04, "change_pct": -5.7},
"cpm": {"value": 7.43, "previous": 6.85, "change": 0.58, "change_pct": 8.5},
"purchases": {"value": 104, "previous": 95, "change": 9, "change_pct": 9.5},
"purchase_value": {"value": 12399.31, "previous": 11411.45, "change": 987.86, "change_pct": 8.7},
"cost_per_purchase": {"value": 27.17, "previous": 30.2, "change": -3.03, "change_pct": -10},
"roas": {"value": 4.39, "previous": 3.98, "change": 0.41, "change_pct": 10.3},
"leads": {"value": 93, "previous": 85, "change": 8, "change_pct": 9.4},
"cost_per_lead": {"value": 30.38, "previous": 33.75, "change": -3.37, "change_pct": -10}
},
"meta": {
"site_id": "YOUR_SITE_ID",
"period": {
"from": "2026-10-17",
"to": "2026-11-13",
"compare_from": "2026-09-19",
"compare_to": "2026-10-16"
},
"currency": "EUR"
}
}
Response fields · in data:
| Field | Type | What it is |
|---|---|---|
compare | string | previous_period or previous_year: what the previous figures are. |
cost | object | Amount spent in the period, against the previous period. |
cost.value | number or null | This period; null when it does not apply. |
cost.previous | number or null | The previous period; null when it does not apply. |
cost.change | number or null | value minus previous. |
cost.change_pct | number or null | The change in percent of previous; null when previous is 0 or null. |
impressions | object | Impressions in the period, against the previous period. |
impressions.value | number or null | This period; null when it does not apply. |
impressions.previous | number or null | The previous period; null when it does not apply. |
impressions.change | number or null | value minus previous. |
impressions.change_pct | number or null | The change in percent of previous; null when previous is 0 or null. |
reach | object | People reached in the period, against the previous period. |
reach.value | number or null | This period; null when it does not apply. |
reach.previous | number or null | The previous period; null when it does not apply. |
reach.change | number or null | value minus previous. |
reach.change_pct | number or null | The change in percent of previous; null when previous is 0 or null. |
frequency | object | Impressions per person reached in the period, against the previous period. |
frequency.value | number or null | This period; null when it does not apply. |
frequency.previous | number or null | The previous period; null when it does not apply. |
frequency.change | number or null | value minus previous. |
frequency.change_pct | number or null | The change in percent of previous; null when previous is 0 or null. |
clicks | object | Link clicks in the period, against the previous period. |
clicks.value | number or null | This period; null when it does not apply. |
clicks.previous | number or null | The previous period; null when it does not apply. |
clicks.change | number or null | value minus previous. |
clicks.change_pct | number or null | The change in percent of previous; null when previous is 0 or null. |
ctr_pct | object | Link CTR, 0-100, in the period, against the previous period. |
ctr_pct.value | number or null | This period; null when it does not apply. |
ctr_pct.previous | number or null | The previous period; null when it does not apply. |
ctr_pct.change | number or null | value minus previous, in percentage points. |
ctr_pct.change_pct | number or null | The change in percent of previous; null when previous is 0 or null. |
average_cpc | object | Cost per link click in the period, against the previous period. |
average_cpc.value | number or null | This period; null when it does not apply. |
average_cpc.previous | number or null | The previous period; null when it does not apply. |
average_cpc.change | number or null | value minus previous. |
average_cpc.change_pct | number or null | The change in percent of previous; null when previous is 0 or null. |
cpm | object | Cost per 1,000 impressions in the period, against the previous period. |
cpm.value | number or null | This period; null when it does not apply. |
cpm.previous | number or null | The previous period; null when it does not apply. |
cpm.change | number or null | value minus previous. |
cpm.change_pct | number or null | The change in percent of previous; null when previous is 0 or null. |
purchases | object | Purchases in the period, against the previous period. |
purchases.value | number or null | This period; null when it does not apply. |
purchases.previous | number or null | The previous period; null when it does not apply. |
purchases.change | number or null | value minus previous. |
purchases.change_pct | number or null | The change in percent of previous; null when previous is 0 or null. |
purchase_value | object | Purchase value in the period, against the previous period. |
purchase_value.value | number or null | This period; null when it does not apply. |
purchase_value.previous | number or null | The previous period; null when it does not apply. |
purchase_value.change | number or null | value minus previous. |
purchase_value.change_pct | number or null | The change in percent of previous; null when previous is 0 or null. |
cost_per_purchase | object | Cost per purchase in the period, against the previous period. |
cost_per_purchase.value | number or null | This period; null when it does not apply. |
cost_per_purchase.previous | number or null | The previous period; null when it does not apply. |
cost_per_purchase.change | number or null | value minus previous. |
cost_per_purchase.change_pct | number or null | The change in percent of previous; null when previous is 0 or null. |
roas | object | ROAS (purchase value / cost) in the period, against the previous period. |
roas.value | number or null | This period; null when it does not apply. |
roas.previous | number or null | The previous period; null when it does not apply. |
roas.change | number or null | value minus previous. |
roas.change_pct | number or null | The change in percent of previous; null when previous is 0 or null. |
leads | object | Leads in the period, against the previous period. |
leads.value | number or null | This period; null when it does not apply. |
leads.previous | number or null | The previous period; null when it does not apply. |
leads.change | number or null | value minus previous. |
leads.change_pct | number or null | The change in percent of previous; null when previous is 0 or null. |
cost_per_lead | object | Cost per lead in the period, against the previous period. |
cost_per_lead.value | number or null | This period; null when it does not apply. |
cost_per_lead.previous | number or null | The previous period; null when it does not apply. |
cost_per_lead.change | number or null | value minus previous. |
cost_per_lead.change_pct | number or null | The change in percent of previous; null when previous is 0 or null. |
metaads.daily
POST /rest/v1/metaads.daily · MCP tool get_metaads_daily
Returns the Meta Ads figures of the chosen ad account of one site per day of the period, oldest first, next to the matching day of the previous period: every metric of metaads.summary except reach and frequency (people reached on one day do not add up to a period). The period runs up to yesterday at the latest; meta.period gives it and the previous period, meta.currency the account currency (EUR). Fails with 409 not_connected when Meta Ads is not connected for the site (or the connection expired: Meta connections last about 60 days), 409 no_account when no ad account is chosen.
Arguments
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
from | string, YYYY-MM-DD | First day of the period, YYYY-MM-DD; give it together with to. |
to | string, YYYY-MM-DD | Last day of the period, YYYY-MM-DD (yesterday at the latest); give it together with from. At most 366 days. |
days | integer, 1 to 366, default 28 | Without from and to: the last this many days up to yesterday. Defaults to 28. |
compare | one of previous_period, previous_year | What the previous figures are: previous_period (the same number of days just before) or previous_year (the same days 52 weeks earlier, same weekdays; for periods up to 364 days). Defaults to previous_period. |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/metaads.daily \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"site_id":"YOUR_SITE_ID","days":28}'
Example response · Sample figures of a made-up web shop.
{
"data": {
"compare": "previous_period",
"days": [
{
"date": "2026-10-17",
"cost": 71.23,
"impressions": 10100,
"clicks": 93,
"ctr_pct": 0.92,
"average_cpc": 0.77,
"cpm": 7.05,
"purchases": 2,
"purchase_value": 270.19,
"cost_per_purchase": 35.62,
"roas": 3.79,
"leads": 1,
"cost_per_lead": 71.23,
"previous_date": "2026-09-19",
"previous": {
"cost": 95.93,
"impressions": 13065,
"clicks": 139,
"ctr_pct": 1.06,
"average_cpc": 0.69,
"cpm": 7.34,
"purchases": 4,
"purchase_value": 432.64,
"cost_per_purchase": 23.98,
"roas": 4.51,
"leads": 3,
"cost_per_lead": 31.98
}
},
{
"date": "2026-10-18",
"cost": 97.63,
"impressions": 13732,
"clicks": 149,
"ctr_pct": 1.09,
"average_cpc": 0.66,
"cpm": 7.11,
"purchases": 3,
"purchase_value": 371.92,
"cost_per_purchase": 32.54,
"roas": 3.81,
"leads": 3,
"cost_per_lead": 32.54,
"previous_date": "2026-09-20",
"previous": {
"cost": 117.3,
"impressions": 17601,
"clicks": 179,
"ctr_pct": 1.02,
"average_cpc": 0.66,
"cpm": 6.66,
"purchases": 3,
"purchase_value": 322.64,
"cost_per_purchase": 39.1,
"roas": 2.75,
"leads": 2,
"cost_per_lead": 58.65
}
},
{
"date": "2026-10-19",
"cost": 114.23,
"impressions": 17681,
"clicks": 168,
"ctr_pct": 0.95,
"average_cpc": 0.68,
"cpm": 6.46,
"purchases": 3,
"purchase_value": 393.34,
"cost_per_purchase": 38.08,
"roas": 3.44,
"leads": 4,
"cost_per_lead": 28.56,
"previous_date": "2026-09-21",
"previous": {
"cost": 110.05,
"impressions": 15552,
"clicks": 158,
"ctr_pct": 1.02,
"average_cpc": 0.7,
"cpm": 7.08,
"purchases": 3,
"purchase_value": 354.23,
"cost_per_purchase": 36.68,
"roas": 3.22,
"leads": 5,
"cost_per_lead": 22.01
}
},
{
"date": "2026-10-20",
"cost": 109.45,
"impressions": 14374,
"clicks": 158,
"ctr_pct": 1.1,
"average_cpc": 0.69,
"cpm": 7.61,
"purchases": 4,
"purchase_value": 443.79,
"cost_per_purchase": 27.36,
"roas": 4.05,
"leads": 3,
"cost_per_lead": 36.48,
"previous_date": "2026-09-22",
"previous": {
"cost": 119.17,
"impressions": 17003,
"clicks": 181,
"ctr_pct": 1.06,
"average_cpc": 0.66,
"cpm": 7.01,
"purchases": 2,
"purchase_value": 311.17,
"cost_per_purchase": 59.59,
"roas": 2.61,
"leads": 3,
"cost_per_lead": 39.72
}
},
{
"date": "2026-10-21",
"cost": 99.2,
"impressions": 15259,
"clicks": 150,
"ctr_pct": 0.98,
"average_cpc": 0.66,
"cpm": 6.5,
"purchases": 3,
"purchase_value": 407.03,
"cost_per_purchase": 33.07,
"roas": 4.1,
"leads": 3,
"cost_per_lead": 33.07,
"previous_date": "2026-09-23",
"previous": {
"cost": 117.83,
"impressions": 17058,
"clicks": 163,
"ctr_pct": 0.96,
"average_cpc": 0.72,
"cpm": 6.91,
"purchases": 4,
"purchase_value": 589.44,
"cost_per_purchase": 29.46,
"roas": 5,
"leads": 2,
"cost_per_lead": 58.92
}
},
{
"date": "2026-10-22",
"cost": 93.27,
"impressions": 12929,
"clicks": 145,
"ctr_pct": 1.12,
"average_cpc": 0.64,
"cpm": 7.21,
"purchases": 4,
"purchase_value": 434.66,
"cost_per_purchase": 23.32,
"roas": 4.66,
"leads": 3,
"cost_per_lead": 31.09,
"previous_date": "2026-09-24",
"previous": {
"cost": 101.27,
"impressions": 14728,
"clicks": 145,
"ctr_pct": 0.98,
"average_cpc": 0.7,
"cpm": 6.88,
"purchases": 3,
"purchase_value": 345.5,
"cost_per_purchase": 33.76,
"roas": 3.41,
"leads": 4,
"cost_per_lead": 25.32
}
},
{
"date": "2026-10-23",
"cost": 102.78,
"impressions": 15166,
"clicks": 143,
"ctr_pct": 0.94,
"average_cpc": 0.72,
"cpm": 6.78,
"purchases": 4,
"purchase_value": 475.69,
"cost_per_purchase": 25.7,
"roas": 4.63,
"leads": 2,
"cost_per_lead": 51.39,
"previous_date": "2026-09-25",
"previous": {
"cost": 102.02,
"impressions": 15228,
"clicks": 164,
"ctr_pct": 1.08,
"average_cpc": 0.62,
"cpm": 6.7,
"purchases": 5,
"purchase_value": 528.18,
"cost_per_purchase": 20.4,
"roas": 5.18,
"leads": 3,
"cost_per_lead": 34.01
}
},
{
"date": "2026-10-24",
"cost": 85.09,
"impressions": 12536,
"clicks": 137,
"ctr_pct": 1.09,
"average_cpc": 0.62,
"cpm": 6.79,
"purchases": 3,
"purchase_value": 323.17,
"cost_per_purchase": 28.36,
"roas": 3.8,
"leads": 2,
"cost_per_lead": 42.55,
"previous_date": "2026-09-26",
"previous": {
"cost": 87.82,
"impressions": 13579,
"clicks": 129,
"ctr_pct": 0.95,
"average_cpc": 0.68,
"cpm": 6.47,
"purchases": 3,
"purchase_value": 349.75,
"cost_per_purchase": 29.27,
"roas": 3.98,
"leads": 2,
"cost_per_lead": 43.91
}
},
{
"date": "2026-10-25",
"cost": 112.73,
"impressions": 16534,
"clicks": 161,
"ctr_pct": 0.97,
"average_cpc": 0.7,
"cpm": 6.82,
"purchases": 5,
"purchase_value": 547.84,
"cost_per_purchase": 22.55,
"roas": 4.86,
"leads": 3,
"cost_per_lead": 37.58,
"previous_date": "2026-09-27",
"previous": {
"cost": 116.6,
"impressions": 16871,
"clicks": 161,
"ctr_pct": 0.95,
"average_cpc": 0.72,
"cpm": 6.91,
"purchases": 4,
"purchase_value": 440.66,
"cost_per_purchase": 29.15,
"roas": 3.78,
"leads": 4,
"cost_per_lead": 29.15
}
},
{
"date": "2026-10-26",
"cost": 107.18,
"impressions": 16803,
"clicks": 155,
"ctr_pct": 0.92,
"average_cpc": 0.69,
"cpm": 6.38,
"purchases": 4,
"purchase_value": 438.99,
"cost_per_purchase": 26.8,
"roas": 4.1,
"leads": 3,
"cost_per_lead": 35.73,
"previous_date": "2026-09-28",
"previous": {
"cost": 110.55,
"impressions": 17413,
"clicks": 174,
"ctr_pct": 1,
"average_cpc": 0.64,
"cpm": 6.35,
"purchases": 4,
"purchase_value": 389.28,
"cost_per_purchase": 27.64,
"roas": 3.52,
"leads": 4,
"cost_per_lead": 27.64
}
},
{
"date": "2026-10-27",
"cost": 112.89,
"impressions": 17386,
"clicks": 150,
"ctr_pct": 0.86,
"average_cpc": 0.75,
"cpm": 6.49,
"purchases": 4,
"purchase_value": 492.85,
"cost_per_purchase": 28.22,
"roas": 4.37,
"leads": 3,
"cost_per_lead": 37.63,
"previous_date": "2026-09-29",
"previous": {
"cost": 110.71,
"impressions": 15156,
"clicks": 130,
"ctr_pct": 0.86,
"average_cpc": 0.85,
"cpm": 7.3,
"purchases": 4,
"purchase_value": 457.16,
"cost_per_purchase": 27.68,
"roas": 4.13,
"leads": 2,
"cost_per_lead": 55.36
}
},
{
"date": "2026-10-28",
"cost": 118.14,
"impressions": 15873,
"clicks": 170,
"ctr_pct": 1.07,
"average_cpc": 0.69,
"cpm": 7.44,
"purchases": 4,
"purchase_value": 435.46,
"cost_per_purchase": 29.54,
"roas": 3.69,
"leads": 3,
"cost_per_lead": 39.38,
"previous_date": "2026-09-30",
"previous": {
"cost": 107.89,
"impressions": 15586,
"clicks": 157,
"ctr_pct": 1.01,
"average_cpc": 0.69,
"cpm": 6.92,
"purchases": 2,
"purchase_value": 283.42,
"cost_per_purchase": 53.95,
"roas": 2.63,
"leads": 3,
"cost_per_lead": 35.96
}
},
{
"date": "2026-10-29",
"cost": 114.02,
"impressions": 15654,
"clicks": 155,
"ctr_pct": 0.99,
"average_cpc": 0.74,
"cpm": 7.28,
"purchases": 5,
"purchase_value": 581.91,
"cost_per_purchase": 22.8,
"roas": 5.1,
"leads": 4,
"cost_per_lead": 28.51,
"previous_date": "2026-10-01",
"previous": {
"cost": 94.01,
"impressions": 14052,
"clicks": 140,
"ctr_pct": 1,
"average_cpc": 0.67,
"cpm": 6.69,
"purchases": 3,
"purchase_value": 385.42,
"cost_per_purchase": 31.34,
"roas": 4.1,
"leads": 2,
"cost_per_lead": 47.01
}
},
{
"date": "2026-10-30",
"cost": 103.58,
"impressions": 15988,
"clicks": 156,
"ctr_pct": 0.98,
"average_cpc": 0.66,
"cpm": 6.48,
"purchases": 3,
"purchase_value": 360.43,
"cost_per_purchase": 34.53,
"roas": 3.48,
"leads": 4,
"cost_per_lead": 25.9,
"previous_date": "2026-10-02",
"previous": {
"cost": 100,
"impressions": 13519,
"clicks": 149,
"ctr_pct": 1.1,
"average_cpc": 0.67,
"cpm": 7.4,
"purchases": 3,
"purchase_value": 333.02,
"cost_per_purchase": 33.33,
"roas": 3.33,
"leads": 2,
"cost_per_lead": 50
}
},
{
"date": "2026-10-31",
"cost": 85.92,
"impressions": 13627,
"clicks": 133,
"ctr_pct": 0.98,
"average_cpc": 0.65,
"cpm": 6.31,
"purchases": 3,
"purchase_value": 363.65,
"cost_per_purchase": 28.64,
"roas": 4.23,
"leads": 4,
"cost_per_lead": 21.48,
"previous_date": "2026-10-03",
"previous": {
"cost": 90.74,
"impressions": 12620,
"clicks": 131,
"ctr_pct": 1.04,
"average_cpc": 0.69,
"cpm": 7.19,
"purchases": 4,
"purchase_value": 431.13,
"cost_per_purchase": 22.69,
"roas": 4.75,
"leads": 3,
"cost_per_lead": 30.25
}
},
{
"date": "2026-11-01",
"cost": 118.08,
"impressions": 17333,
"clicks": 173,
"ctr_pct": 1,
"average_cpc": 0.68,
"cpm": 6.81,
"purchases": 4,
"purchase_value": 399.66,
"cost_per_purchase": 29.52,
"roas": 3.38,
"leads": 4,
"cost_per_lead": 29.52,
"previous_date": "2026-10-04",
"previous": {
"cost": 107.46,
"impressions": 16410,
"clicks": 145,
"ctr_pct": 0.88,
"average_cpc": 0.74,
"cpm": 6.55,
"purchases": 4,
"purchase_value": 489.57,
"cost_per_purchase": 26.87,
"roas": 4.56,
"leads": 2,
"cost_per_lead": 53.73
}
},
{
"date": "2026-11-02",
"cost": 113.23,
"impressions": 16694,
"clicks": 169,
"ctr_pct": 1.01,
"average_cpc": 0.67,
"cpm": 6.78,
"purchases": 4,
"purchase_value": 460.21,
"cost_per_purchase": 28.31,
"roas": 4.06,
"leads": 2,
"cost_per_lead": 56.62,
"previous_date": "2026-10-05",
"previous": {
"cost": 108.17,
"impressions": 16813,
"clicks": 169,
"ctr_pct": 1.01,
"average_cpc": 0.64,
"cpm": 6.43,
"purchases": 5,
"purchase_value": 666.34,
"cost_per_purchase": 21.63,
"roas": 6.16,
"leads": 4,
"cost_per_lead": 27.04
}
},
{
"date": "2026-11-03",
"cost": 110.88,
"impressions": 14851,
"clicks": 151,
"ctr_pct": 1.02,
"average_cpc": 0.73,
"cpm": 7.47,
"purchases": 3,
"purchase_value": 398.2,
"cost_per_purchase": 36.96,
"roas": 3.59,
"leads": 3,
"cost_per_lead": 36.96,
"previous_date": "2026-10-06",
"previous": {
"cost": 105.44,
"impressions": 16295,
"clicks": 148,
"ctr_pct": 0.91,
"average_cpc": 0.71,
"cpm": 6.47,
"purchases": 3,
"purchase_value": 313.84,
"cost_per_purchase": 35.15,
"roas": 2.98,
"leads": 3,
"cost_per_lead": 35.15
}
},
{
"date": "2026-11-04",
"cost": 99.94,
"impressions": 10937,
"clicks": 145,
"ctr_pct": 1.33,
"average_cpc": 0.69,
"cpm": 9.14,
"purchases": 4,
"purchase_value": 554.21,
"cost_per_purchase": 24.99,
"roas": 5.55,
"leads": 4,
"cost_per_lead": 24.99,
"previous_date": "2026-10-07",
"previous": {
"cost": 106.08,
"impressions": 15361,
"clicks": 128,
"ctr_pct": 0.83,
"average_cpc": 0.83,
"cpm": 6.91,
"purchases": 3,
"purchase_value": 349.32,
"cost_per_purchase": 35.36,
"roas": 3.29,
"leads": 3,
"cost_per_lead": 35.36
}
},
{
"date": "2026-11-05",
"cost": 93.06,
"impressions": 10832,
"clicks": 171,
"ctr_pct": 1.58,
"average_cpc": 0.54,
"cpm": 8.59,
"purchases": 5,
"purchase_value": 627,
"cost_per_purchase": 18.61,
"roas": 6.74,
"leads": 5,
"cost_per_lead": 18.61,
"previous_date": "2026-10-08",
"previous": {
"cost": 86.78,
"impressions": 11721,
"clicks": 105,
"ctr_pct": 0.9,
"average_cpc": 0.83,
"cpm": 7.4,
"purchases": 3,
"purchase_value": 317.7,
"cost_per_purchase": 28.93,
"roas": 3.66,
"leads": 2,
"cost_per_lead": 43.39
}
},
{
"date": "2026-11-06",
"cost": 97.04,
"impressions": 11435,
"clicks": 155,
"ctr_pct": 1.36,
"average_cpc": 0.63,
"cpm": 8.49,
"purchases": 6,
"purchase_value": 649.6,
"cost_per_purchase": 16.17,
"roas": 6.69,
"leads": 3,
"cost_per_lead": 32.35,
"previous_date": "2026-10-09",
"previous": {
"cost": 80.55,
"impressions": 11956,
"clicks": 129,
"ctr_pct": 1.08,
"average_cpc": 0.62,
"cpm": 6.74,
"purchases": 3,
"purchase_value": 339.21,
"cost_per_purchase": 26.85,
"roas": 4.21,
"leads": 4,
"cost_per_lead": 20.14
}
},
{
"date": "2026-11-07",
"cost": 87.46,
"impressions": 9044,
"clicks": 105,
"ctr_pct": 1.16,
"average_cpc": 0.83,
"cpm": 9.67,
"purchases": 2,
"purchase_value": 289,
"cost_per_purchase": 43.73,
"roas": 3.3,
"leads": 2,
"cost_per_lead": 43.73,
"previous_date": "2026-10-10",
"previous": {
"cost": 89.48,
"impressions": 12900,
"clicks": 129,
"ctr_pct": 1,
"average_cpc": 0.69,
"cpm": 6.94,
"purchases": 3,
"purchase_value": 414.32,
"cost_per_purchase": 29.83,
"roas": 4.63,
"leads": 2,
"cost_per_lead": 44.74
}
},
{
"date": "2026-11-08",
"cost": 96.1,
"impressions": 11738,
"clicks": 167,
"ctr_pct": 1.42,
"average_cpc": 0.58,
"cpm": 8.19,
"purchases": 3,
"purchase_value": 427.89,
"cost_per_purchase": 32.03,
"roas": 4.45,
"leads": 4,
"cost_per_lead": 24.03,
"previous_date": "2026-10-11",
"previous": {
"cost": 96.63,
"impressions": 13126,
"clicks": 120,
"ctr_pct": 0.91,
"average_cpc": 0.81,
"cpm": 7.36,
"purchases": 3,
"purchase_value": 405.01,
"cost_per_purchase": 32.21,
"roas": 4.19,
"leads": 3,
"cost_per_lead": 32.21
}
},
{
"date": "2026-11-09",
"cost": 96.11,
"impressions": 11693,
"clicks": 189,
"ctr_pct": 1.62,
"average_cpc": 0.51,
"cpm": 8.22,
"purchases": 4,
"purchase_value": 485.29,
"cost_per_purchase": 24.03,
"roas": 5.05,
"leads": 4,
"cost_per_lead": 24.03,
"previous_date": "2026-10-12",
"previous": {
"cost": 99.65,
"impressions": 13560,
"clicks": 126,
"ctr_pct": 0.93,
"average_cpc": 0.79,
"cpm": 7.35,
"purchases": 4,
"purchase_value": 456.54,
"cost_per_purchase": 24.91,
"roas": 4.58,
"leads": 3,
"cost_per_lead": 33.22
}
},
{
"date": "2026-11-10",
"cost": 92.67,
"impressions": 9906,
"clicks": 153,
"ctr_pct": 1.54,
"average_cpc": 0.61,
"cpm": 9.35,
"purchases": 3,
"purchase_value": 332.12,
"cost_per_purchase": 30.89,
"roas": 3.58,
"leads": 3,
"cost_per_lead": 30.89,
"previous_date": "2026-10-13",
"previous": {
"cost": 109.32,
"impressions": 16702,
"clicks": 148,
"ctr_pct": 0.89,
"average_cpc": 0.74,
"cpm": 6.55,
"purchases": 3,
"purchase_value": 344.25,
"cost_per_purchase": 36.44,
"roas": 3.15,
"leads": 2,
"cost_per_lead": 54.66
}
},
{
"date": "2026-11-11",
"cost": 100.86,
"impressions": 10722,
"clicks": 156,
"ctr_pct": 1.45,
"average_cpc": 0.65,
"cpm": 9.41,
"purchases": 3,
"purchase_value": 352.01,
"cost_per_purchase": 33.62,
"roas": 3.49,
"leads": 3,
"cost_per_lead": 33.62,
"previous_date": "2026-10-14",
"previous": {
"cost": 115.33,
"impressions": 18394,
"clicks": 205,
"ctr_pct": 1.11,
"average_cpc": 0.56,
"cpm": 6.27,
"purchases": 5,
"purchase_value": 653.02,
"cost_per_purchase": 23.07,
"roas": 5.66,
"leads": 6,
"cost_per_lead": 19.22
}
},
{
"date": "2026-11-12",
"cost": 96.69,
"impressions": 10115,
"clicks": 155,
"ctr_pct": 1.53,
"average_cpc": 0.62,
"cpm": 9.56,
"purchases": 5,
"purchase_value": 618.43,
"cost_per_purchase": 19.34,
"roas": 6.4,
"leads": 6,
"cost_per_lead": 16.12,
"previous_date": "2026-10-15",
"previous": {
"cost": 91.22,
"impressions": 14255,
"clicks": 138,
"ctr_pct": 0.97,
"average_cpc": 0.66,
"cpm": 6.4,
"purchases": 3,
"purchase_value": 389.75,
"cost_per_purchase": 30.41,
"roas": 4.27,
"leads": 3,
"cost_per_lead": 30.41
}
},
{
"date": "2026-11-13",
"cost": 95.89,
"impressions": 11175,
"clicks": 162,
"ctr_pct": 1.45,
"average_cpc": 0.59,
"cpm": 8.58,
"purchases": 4,
"purchase_value": 464.78,
"cost_per_purchase": 23.97,
"roas": 4.85,
"leads": 4,
"cost_per_lead": 23.97,
"previous_date": "2026-10-16",
"previous": {
"cost": 90.6,
"impressions": 12366,
"clicks": 131,
"ctr_pct": 1.06,
"average_cpc": 0.69,
"cpm": 7.33,
"purchases": 3,
"purchase_value": 318.91,
"cost_per_purchase": 30.2,
"roas": 3.52,
"leads": 2,
"cost_per_lead": 45.3
}
}
]
},
"meta": {
"site_id": "YOUR_SITE_ID",
"period": {
"from": "2026-10-17",
"to": "2026-11-13",
"compare_from": "2026-09-19",
"compare_to": "2026-10-16"
},
"currency": "EUR"
}
}
Response fields · in data:
| Field | Type | What it is |
|---|---|---|
compare | string | previous_period or previous_year: what the previous figures are. |
days | array | Per day of the period, oldest first. |
days[].date | string | The day, YYYY-MM-DD. |
days[].cost | number | Amount spent, in the currency of the ad account (meta.currency). |
days[].impressions | integer | Impressions. |
days[].clicks | integer | Link clicks (clicks to the website, app or form; not likes, comments or profile clicks). |
days[].ctr_pct | number or null | Link clicks as a share of impressions, 0-100; null without impressions. |
days[].average_cpc | number or null | Cost per link click; null without link clicks. |
days[].cpm | number or null | Cost per 1,000 impressions; null without impressions. |
days[].purchases | number | Purchases attributed to the ads (website, app and shop together, as Meta counts them with the account's attribution setting). |
days[].purchase_value | number | Value of those purchases, in the account currency. |
days[].cost_per_purchase | number or null | Cost per purchase; null without purchases. |
days[].roas | number or null | Return on ad spend: purchase_value divided by cost (3.5 = 3.5 times the cost back); null without cost. |
days[].leads | number | Leads (forms on Facebook and Instagram and leads on the website). |
days[].cost_per_lead | number or null | Cost per lead; null without leads. |
days[].previous_date | string | The matching day of the previous period, YYYY-MM-DD. |
days[].previous | object | The same figures on previous_date. |
days[].previous.cost | number | Amount spent, in the currency of the ad account (meta.currency). |
days[].previous.impressions | integer | Impressions. |
days[].previous.clicks | integer | Link clicks (clicks to the website, app or form; not likes, comments or profile clicks). |
days[].previous.ctr_pct | number or null | Link clicks as a share of impressions, 0-100; null without impressions. |
days[].previous.average_cpc | number or null | Cost per link click; null without link clicks. |
days[].previous.cpm | number or null | Cost per 1,000 impressions; null without impressions. |
days[].previous.purchases | number | Purchases attributed to the ads (website, app and shop together, as Meta counts them with the account's attribution setting). |
days[].previous.purchase_value | number | Value of those purchases, in the account currency. |
days[].previous.cost_per_purchase | number or null | Cost per purchase; null without purchases. |
days[].previous.roas | number or null | Return on ad spend: purchase_value divided by cost (3.5 = 3.5 times the cost back); null without cost. |
days[].previous.leads | number | Leads (forms on Facebook and Instagram and leads on the website). |
days[].previous.cost_per_lead | number or null | Cost per lead; null without leads. |
metaads.campaigns
POST /rest/v1/metaads.campaigns · MCP tool get_metaads_campaigns
Returns the campaigns of the chosen Meta ad account of one site that had impressions in the period, most spent first: status, objective and budget, all metrics, the share of the cost and the same figures in the previous period. The period runs up to yesterday at the latest; meta.period gives it and the previous period, meta.currency the account currency (EUR). Fails with 409 not_connected when Meta Ads is not connected for the site (or the connection expired: Meta connections last about 60 days), 409 no_account when no ad account is chosen.
Arguments
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
from | string, YYYY-MM-DD | First day of the period, YYYY-MM-DD; give it together with to. |
to | string, YYYY-MM-DD | Last day of the period, YYYY-MM-DD (yesterday at the latest); give it together with from. At most 366 days. |
days | integer, 1 to 366, default 28 | Without from and to: the last this many days up to yesterday. Defaults to 28. |
compare | one of previous_period, previous_year | What the previous figures are: previous_period (the same number of days just before) or previous_year (the same days 52 weeks earlier, same weekdays; for periods up to 364 days). Defaults to previous_period. |
limit | integer, 1 to 500, default 100 | Items per call. |
cursor | string | meta.next_cursor of the previous call, for the next page. |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/metaads.campaigns \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"site_id":"YOUR_SITE_ID","days":28,"limit":2}'
Example response · Sample figures of a made-up web shop.
{
"data": [
{
"campaign_id": "120200000091384315",
"campaign": "Prospecting | Running shoes",
"status": "active",
"objective": "sales",
"daily_budget": 65,
"lifetime_budget": null,
"cost": 1563.66,
"impressions": 189625,
"reach": 111544,
"frequency": 1.7,
"clicks": 2088,
"ctr_pct": 1.1,
"average_cpc": 0.75,
"cpm": 8.25,
"purchases": 41,
"purchase_value": 5193.4,
"cost_per_purchase": 38.14,
"roas": 3.32,
"leads": 0,
"cost_per_lead": null,
"share_pct": 55.3,
"previous": {
"cost": 1501.54,
"impressions": 178334,
"reach": 104902,
"frequency": 1.7,
"clicks": 1935,
"ctr_pct": 1.09,
"average_cpc": 0.78,
"cpm": 8.42,
"purchases": 41,
"purchase_value": 5219.6,
"cost_per_purchase": 36.62,
"roas": 3.48,
"leads": 0,
"cost_per_lead": null
}
},
{
"campaign_id": "120200000016043000",
"campaign": "Retargeting | Cart abandoners",
"status": "active",
"objective": "sales",
"daily_budget": 25,
"lifetime_budget": null,
"cost": 602.5,
"impressions": 39894,
"reach": 11082,
"frequency": 3.6,
"clicks": 984,
"ctr_pct": 2.47,
"average_cpc": 0.61,
"cpm": 15.1,
"purchases": 61,
"purchase_value": 7063.89,
"cost_per_purchase": 9.88,
"roas": 11.72,
"leads": 0,
"cost_per_lead": null,
"share_pct": 21.3,
"previous": {
"cost": 566.73,
"impressions": 36576,
"reach": 10160,
"frequency": 3.6,
"clicks": 887,
"ctr_pct": 2.43,
"average_cpc": 0.64,
"cpm": 15.49,
"purchases": 52,
"purchase_value": 5958.4,
"cost_per_purchase": 10.9,
"roas": 10.51,
"leads": 0,
"cost_per_lead": null
}
}
],
"meta": {
"site_id": "YOUR_SITE_ID",
"next_cursor": "2",
"total": 4,
"period": {
"from": "2026-10-17",
"to": "2026-11-13",
"compare_from": "2026-09-19",
"compare_to": "2026-10-16"
},
"currency": "EUR"
}
}
Response fields · data is a list; each item has:
| Field | Type | What it is |
|---|---|---|
campaign_id | string | The campaign id in Meta. |
campaign | string | The campaign name. |
status | string or null | Its delivery status now (not in the period): active, paused, campaign_paused, adset_paused, archived, in_process, with_issues, … |
objective | string or null | What the campaign is set to achieve: sales, leads, traffic, awareness, engagement or app_promotion (older objectives are mapped). |
daily_budget | number or null | The daily budget of the campaign now, in the account currency; null when the budget is set per ad set or as a lifetime budget. |
lifetime_budget | number or null | The lifetime budget of the campaign now; null when it has none. |
cost | number | Amount spent, in the currency of the ad account (meta.currency). |
impressions | integer | Impressions. |
reach | integer | People reached at least once in the period (counted once however often they saw an ad, so reach does not add up over days or rows). |
frequency | number or null | Impressions per person reached; null without reach. |
clicks | integer | Link clicks (clicks to the website, app or form; not likes, comments or profile clicks). |
ctr_pct | number or null | Link clicks as a share of impressions, 0-100; null without impressions. |
average_cpc | number or null | Cost per link click; null without link clicks. |
cpm | number or null | Cost per 1,000 impressions; null without impressions. |
purchases | number | Purchases attributed to the ads (website, app and shop together, as Meta counts them with the account's attribution setting). |
purchase_value | number | Value of those purchases, in the account currency. |
cost_per_purchase | number or null | Cost per purchase; null without purchases. |
roas | number or null | Return on ad spend: purchase_value divided by cost (3.5 = 3.5 times the cost back); null without cost. |
leads | number | Leads (forms on Facebook and Instagram and leads on the website). |
cost_per_lead | number or null | Cost per lead; null without leads. |
share_pct | number or null | Share of the cost of the whole list, 0-100; null when the list cost nothing. |
previous | object or null | The same figures in the previous period; null when it had no impressions then. |
previous.cost | number | Amount spent, in the currency of the ad account (meta.currency). |
previous.impressions | integer | Impressions. |
previous.reach | integer | People reached at least once in the period (counted once however often they saw an ad, so reach does not add up over days or rows). |
previous.frequency | number or null | Impressions per person reached; null without reach. |
previous.clicks | integer | Link clicks (clicks to the website, app or form; not likes, comments or profile clicks). |
previous.ctr_pct | number or null | Link clicks as a share of impressions, 0-100; null without impressions. |
previous.average_cpc | number or null | Cost per link click; null without link clicks. |
previous.cpm | number or null | Cost per 1,000 impressions; null without impressions. |
previous.purchases | number | Purchases attributed to the ads (website, app and shop together, as Meta counts them with the account's attribution setting). |
previous.purchase_value | number | Value of those purchases, in the account currency. |
previous.cost_per_purchase | number or null | Cost per purchase; null without purchases. |
previous.roas | number or null | Return on ad spend: purchase_value divided by cost (3.5 = 3.5 times the cost back); null without cost. |
previous.leads | number | Leads (forms on Facebook and Instagram and leads on the website). |
previous.cost_per_lead | number or null | Cost per lead; null without leads. |
metaads.adsets
POST /rest/v1/metaads.adsets · MCP tool get_metaads_adsets
Returns the ad sets of the chosen Meta ad account of one site that had impressions in the period, most spent first, optionally of one campaign: status, budget, campaign, all metrics and the previous period. The period runs up to yesterday at the latest; meta.period gives it and the previous period, meta.currency the account currency (EUR). Fails with 409 not_connected when Meta Ads is not connected for the site (or the connection expired: Meta connections last about 60 days), 409 no_account when no ad account is chosen.
Arguments
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
from | string, YYYY-MM-DD | First day of the period, YYYY-MM-DD; give it together with to. |
to | string, YYYY-MM-DD | Last day of the period, YYYY-MM-DD (yesterday at the latest); give it together with from. At most 366 days. |
days | integer, 1 to 366, default 28 | Without from and to: the last this many days up to yesterday. Defaults to 28. |
compare | one of previous_period, previous_year | What the previous figures are: previous_period (the same number of days just before) or previous_year (the same days 52 weeks earlier, same weekdays; for periods up to 364 days). Defaults to previous_period. |
campaign_id | string | Only this campaign (its campaign_id from metaads.campaigns). |
limit | integer, 1 to 500, default 100 | Items per call. |
cursor | string | meta.next_cursor of the previous call, for the next page. |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/metaads.adsets \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"site_id":"YOUR_SITE_ID","days":28,"limit":2,"campaign_id":"120200000091384315"}'
Example response · Sample figures of a made-up web shop.
{
"data": [
{
"adset_id": "120200000046103535",
"adset": "Interest running",
"status": "active",
"daily_budget": null,
"lifetime_budget": null,
"campaign_id": "120200000091384315",
"campaign": "Prospecting | Running shoes",
"cost": 781.83,
"impressions": 94813,
"reach": 55772,
"frequency": 1.7,
"clicks": 868,
"ctr_pct": 0.92,
"average_cpc": 0.9,
"cpm": 8.25,
"purchases": 18,
"purchase_value": 2289.77,
"cost_per_purchase": 43.44,
"roas": 2.93,
"leads": 0,
"cost_per_lead": null,
"share_pct": 50,
"previous": {
"cost": 750.77,
"impressions": 89167,
"reach": 52451,
"frequency": 1.7,
"clicks": 805,
"ctr_pct": 0.9,
"average_cpc": 0.93,
"cpm": 8.42,
"purchases": 18,
"purchase_value": 2301.32,
"cost_per_purchase": 41.71,
"roas": 3.07,
"leads": 0,
"cost_per_lead": null
}
},
{
"adset_id": "120200000068209849",
"adset": "Lookalike buyers",
"status": "active",
"daily_budget": null,
"lifetime_budget": null,
"campaign_id": "120200000091384315",
"campaign": "Prospecting | Running shoes",
"cost": 547.28,
"impressions": 66369,
"reach": 39041,
"frequency": 1.7,
"clicks": 567,
"ctr_pct": 0.85,
"average_cpc": 0.97,
"cpm": 8.25,
"purchases": 15,
"purchase_value": 1866.77,
"cost_per_purchase": 36.49,
"roas": 3.41,
"leads": 0,
"cost_per_lead": null,
"share_pct": 35,
"previous": {
"cost": 525.54,
"impressions": 62417,
"reach": 36716,
"frequency": 1.7,
"clicks": 526,
"ctr_pct": 0.84,
"average_cpc": 1,
"cpm": 8.42,
"purchases": 15,
"purchase_value": 1876.19,
"cost_per_purchase": 35.04,
"roas": 3.57,
"leads": 0,
"cost_per_lead": null
}
}
],
"meta": {
"site_id": "YOUR_SITE_ID",
"next_cursor": "2",
"total": 3,
"period": {
"from": "2026-10-17",
"to": "2026-11-13",
"compare_from": "2026-09-19",
"compare_to": "2026-10-16"
},
"currency": "EUR"
}
}
Response fields · data is a list; each item has:
| Field | Type | What it is |
|---|---|---|
adset_id | string | The ad set id in Meta. |
adset | string | The ad set name. |
status | string or null | Its delivery status now (not in the period): active, paused, campaign_paused, adset_paused, archived, in_process, with_issues, … |
daily_budget | number or null | The daily budget of the ad set now; null when the campaign holds the budget. |
lifetime_budget | number or null | The lifetime budget of the ad set now; null when it has none. |
campaign_id | string | Its campaign. |
campaign | string | The campaign name. |
cost | number | Amount spent, in the currency of the ad account (meta.currency). |
impressions | integer | Impressions. |
reach | integer | People reached at least once in the period (counted once however often they saw an ad, so reach does not add up over days or rows). |
frequency | number or null | Impressions per person reached; null without reach. |
clicks | integer | Link clicks (clicks to the website, app or form; not likes, comments or profile clicks). |
ctr_pct | number or null | Link clicks as a share of impressions, 0-100; null without impressions. |
average_cpc | number or null | Cost per link click; null without link clicks. |
cpm | number or null | Cost per 1,000 impressions; null without impressions. |
purchases | number | Purchases attributed to the ads (website, app and shop together, as Meta counts them with the account's attribution setting). |
purchase_value | number | Value of those purchases, in the account currency. |
cost_per_purchase | number or null | Cost per purchase; null without purchases. |
roas | number or null | Return on ad spend: purchase_value divided by cost (3.5 = 3.5 times the cost back); null without cost. |
leads | number | Leads (forms on Facebook and Instagram and leads on the website). |
cost_per_lead | number or null | Cost per lead; null without leads. |
share_pct | number or null | Share of the cost of the whole list, 0-100; null when the list cost nothing. |
previous | object or null | The same figures in the previous period; null when it had no impressions then. |
previous.cost | number | Amount spent, in the currency of the ad account (meta.currency). |
previous.impressions | integer | Impressions. |
previous.reach | integer | People reached at least once in the period (counted once however often they saw an ad, so reach does not add up over days or rows). |
previous.frequency | number or null | Impressions per person reached; null without reach. |
previous.clicks | integer | Link clicks (clicks to the website, app or form; not likes, comments or profile clicks). |
previous.ctr_pct | number or null | Link clicks as a share of impressions, 0-100; null without impressions. |
previous.average_cpc | number or null | Cost per link click; null without link clicks. |
previous.cpm | number or null | Cost per 1,000 impressions; null without impressions. |
previous.purchases | number | Purchases attributed to the ads (website, app and shop together, as Meta counts them with the account's attribution setting). |
previous.purchase_value | number | Value of those purchases, in the account currency. |
previous.cost_per_purchase | number or null | Cost per purchase; null without purchases. |
previous.roas | number or null | Return on ad spend: purchase_value divided by cost (3.5 = 3.5 times the cost back); null without cost. |
previous.leads | number | Leads (forms on Facebook and Instagram and leads on the website). |
previous.cost_per_lead | number or null | Cost per lead; null without leads. |
metaads.ads
POST /rest/v1/metaads.ads · MCP tool get_metaads_ads
Returns the ads of the chosen Meta ad account of one site that had impressions in the period, most spent first, optionally of one campaign or one ad set: status, ad set, campaign, all metrics and the previous period. The period runs up to yesterday at the latest; meta.period gives it and the previous period, meta.currency the account currency (EUR). Fails with 409 not_connected when Meta Ads is not connected for the site (or the connection expired: Meta connections last about 60 days), 409 no_account when no ad account is chosen.
Arguments
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
from | string, YYYY-MM-DD | First day of the period, YYYY-MM-DD; give it together with to. |
to | string, YYYY-MM-DD | Last day of the period, YYYY-MM-DD (yesterday at the latest); give it together with from. At most 366 days. |
days | integer, 1 to 366, default 28 | Without from and to: the last this many days up to yesterday. Defaults to 28. |
compare | one of previous_period, previous_year | What the previous figures are: previous_period (the same number of days just before) or previous_year (the same days 52 weeks earlier, same weekdays; for periods up to 364 days). Defaults to previous_period. |
campaign_id | string | Only this campaign (its campaign_id from metaads.campaigns). |
adset_id | string | Only this ad set (its adset_id from metaads.adsets). |
limit | integer, 1 to 500, default 100 | Items per call. |
cursor | string | meta.next_cursor of the previous call, for the next page. |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/metaads.ads \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"site_id":"YOUR_SITE_ID","days":28,"limit":2,"adset_id":"120200000046103535"}'
Example response · Sample figures of a made-up web shop.
{
"data": [
{
"ad_id": "120200000028484411",
"ad": "Video 15 sec",
"status": "active",
"adset_id": "120200000046103535",
"adset": "Interest running",
"campaign_id": "120200000091384315",
"campaign": "Prospecting | Running shoes",
"cost": 453.46,
"impressions": 54991,
"reach": 32348,
"frequency": 1.7,
"clicks": 784,
"ctr_pct": 1.43,
"average_cpc": 0.58,
"cpm": 8.25,
"purchases": 15,
"purchase_value": 1859.26,
"cost_per_purchase": 30.23,
"roas": 4.1,
"leads": 0,
"cost_per_lead": null,
"share_pct": 58,
"previous": {
"cost": 435.45,
"impressions": 51717,
"reach": 30422,
"frequency": 1.7,
"clicks": 726,
"ctr_pct": 1.4,
"average_cpc": 0.6,
"cpm": 8.42,
"purchases": 15,
"purchase_value": 1868.64,
"cost_per_purchase": 29.03,
"roas": 4.29,
"leads": 0,
"cost_per_lead": null
}
},
{
"ad_id": "120200000054931153",
"ad": "Carousel",
"status": "active",
"adset_id": "120200000046103535",
"adset": "Interest running",
"campaign_id": "120200000091384315",
"campaign": "Prospecting | Running shoes",
"cost": 328.37,
"impressions": 39821,
"reach": 23424,
"frequency": 1.7,
"clicks": 426,
"ctr_pct": 1.07,
"average_cpc": 0.77,
"cpm": 8.25,
"purchases": 11,
"purchase_value": 1388.9,
"cost_per_purchase": 29.85,
"roas": 4.23,
"leads": 0,
"cost_per_lead": null,
"share_pct": 42,
"previous": {
"cost": 315.32,
"impressions": 37450,
"reach": 22029,
"frequency": 1.7,
"clicks": 395,
"ctr_pct": 1.05,
"average_cpc": 0.8,
"cpm": 8.42,
"purchases": 11,
"purchase_value": 1395.9,
"cost_per_purchase": 28.67,
"roas": 4.43,
"leads": 0,
"cost_per_lead": null
}
}
],
"meta": {
"site_id": "YOUR_SITE_ID",
"next_cursor": null,
"total": 2,
"period": {
"from": "2026-10-17",
"to": "2026-11-13",
"compare_from": "2026-09-19",
"compare_to": "2026-10-16"
},
"currency": "EUR"
}
}
Response fields · data is a list; each item has:
| Field | Type | What it is |
|---|---|---|
ad_id | string | The ad id in Meta. |
ad | string | The ad name. |
status | string or null | Its delivery status now (not in the period): active, paused, campaign_paused, adset_paused, archived, in_process, with_issues, … |
adset_id | string | Its ad set. |
adset | string | The ad set name. |
campaign_id | string | Its campaign. |
campaign | string | The campaign name. |
cost | number | Amount spent, in the currency of the ad account (meta.currency). |
impressions | integer | Impressions. |
reach | integer | People reached at least once in the period (counted once however often they saw an ad, so reach does not add up over days or rows). |
frequency | number or null | Impressions per person reached; null without reach. |
clicks | integer | Link clicks (clicks to the website, app or form; not likes, comments or profile clicks). |
ctr_pct | number or null | Link clicks as a share of impressions, 0-100; null without impressions. |
average_cpc | number or null | Cost per link click; null without link clicks. |
cpm | number or null | Cost per 1,000 impressions; null without impressions. |
purchases | number | Purchases attributed to the ads (website, app and shop together, as Meta counts them with the account's attribution setting). |
purchase_value | number | Value of those purchases, in the account currency. |
cost_per_purchase | number or null | Cost per purchase; null without purchases. |
roas | number or null | Return on ad spend: purchase_value divided by cost (3.5 = 3.5 times the cost back); null without cost. |
leads | number | Leads (forms on Facebook and Instagram and leads on the website). |
cost_per_lead | number or null | Cost per lead; null without leads. |
share_pct | number or null | Share of the cost of the whole list, 0-100; null when the list cost nothing. |
previous | object or null | The same figures in the previous period; null when it had no impressions then. |
previous.cost | number | Amount spent, in the currency of the ad account (meta.currency). |
previous.impressions | integer | Impressions. |
previous.reach | integer | People reached at least once in the period (counted once however often they saw an ad, so reach does not add up over days or rows). |
previous.frequency | number or null | Impressions per person reached; null without reach. |
previous.clicks | integer | Link clicks (clicks to the website, app or form; not likes, comments or profile clicks). |
previous.ctr_pct | number or null | Link clicks as a share of impressions, 0-100; null without impressions. |
previous.average_cpc | number or null | Cost per link click; null without link clicks. |
previous.cpm | number or null | Cost per 1,000 impressions; null without impressions. |
previous.purchases | number | Purchases attributed to the ads (website, app and shop together, as Meta counts them with the account's attribution setting). |
previous.purchase_value | number | Value of those purchases, in the account currency. |
previous.cost_per_purchase | number or null | Cost per purchase; null without purchases. |
previous.roas | number or null | Return on ad spend: purchase_value divided by cost (3.5 = 3.5 times the cost back); null without cost. |
previous.leads | number | Leads (forms on Facebook and Instagram and leads on the website). |
previous.cost_per_lead | number or null | Cost per lead; null without leads. |
metaads.placements
POST /rest/v1/metaads.placements · MCP tool get_metaads_placements
Returns the Meta Ads figures of the chosen ad account of one site per platform the ads ran on (facebook, instagram, messenger, audience_network, threads) in the period, most spent first, with the previous period. The period runs up to yesterday at the latest; meta.period gives it and the previous period, meta.currency the account currency (EUR). Fails with 409 not_connected when Meta Ads is not connected for the site (or the connection expired: Meta connections last about 60 days), 409 no_account when no ad account is chosen.
Arguments
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
from | string, YYYY-MM-DD | First day of the period, YYYY-MM-DD; give it together with to. |
to | string, YYYY-MM-DD | Last day of the period, YYYY-MM-DD (yesterday at the latest); give it together with from. At most 366 days. |
days | integer, 1 to 366, default 28 | Without from and to: the last this many days up to yesterday. Defaults to 28. |
compare | one of previous_period, previous_year | What the previous figures are: previous_period (the same number of days just before) or previous_year (the same days 52 weeks earlier, same weekdays; for periods up to 364 days). Defaults to previous_period. |
limit | integer, 1 to 500, default 100 | Items per call. |
cursor | string | meta.next_cursor of the previous call, for the next page. |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/metaads.placements \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"site_id":"YOUR_SITE_ID","days":28}'
Example response · Sample figures of a made-up web shop.
{
"data": [
{
"placement": "instagram",
"cost": 1448,
"impressions": 178655,
"reach": 73801,
"frequency": 2.42,
"clicks": 2101,
"ctr_pct": 1.18,
"average_cpc": 0.69,
"cpm": 8.11,
"purchases": 45,
"purchase_value": 5304.26,
"cost_per_purchase": 32.18,
"roas": 3.66,
"leads": 40,
"cost_per_lead": 36.2,
"share_pct": 51.3,
"previous": {
"cost": 1470.17,
"impressions": 196878,
"reach": 79782,
"frequency": 2.47,
"clicks": 2026,
"ctr_pct": 1.03,
"average_cpc": 0.73,
"cpm": 7.47,
"purchases": 41,
"purchase_value": 4881.67,
"cost_per_purchase": 35.86,
"roas": 3.32,
"leads": 36,
"cost_per_lead": 40.84
}
},
{
"placement": "facebook",
"cost": 1138.42,
"impressions": 167251,
"reach": 69090,
"frequency": 2.42,
"clicks": 1725,
"ctr_pct": 1.03,
"average_cpc": 0.66,
"cpm": 6.81,
"purchases": 45,
"purchase_value": 5382.73,
"cost_per_purchase": 25.3,
"roas": 4.73,
"leads": 40,
"cost_per_lead": 28.46,
"share_pct": 40.3,
"previous": {
"cost": 1155.85,
"impressions": 184312,
"reach": 74689,
"frequency": 2.47,
"clicks": 1664,
"ctr_pct": 0.9,
"average_cpc": 0.69,
"cpm": 6.27,
"purchases": 41,
"purchase_value": 4953.88,
"cost_per_purchase": 28.19,
"roas": 4.29,
"leads": 37,
"cost_per_lead": 31.24
}
},
{
"placement": "audience_network",
"cost": 158.25,
"impressions": 22807,
"reach": 9421,
"frequency": 2.42,
"clicks": 336,
"ctr_pct": 1.47,
"average_cpc": 0.47,
"cpm": 6.94,
"purchases": 12,
"purchase_value": 1436.63,
"cost_per_purchase": 13.19,
"roas": 9.08,
"leads": 11,
"cost_per_lead": 14.39,
"share_pct": 5.6,
"previous": {
"cost": 160.67,
"impressions": 25133,
"reach": 10185,
"frequency": 2.47,
"clicks": 324,
"ctr_pct": 1.29,
"average_cpc": 0.5,
"cpm": 6.39,
"purchases": 11,
"purchase_value": 1322.17,
"cost_per_purchase": 14.61,
"roas": 8.23,
"leads": 10,
"cost_per_lead": 16.07
}
},
{
"placement": "messenger",
"cost": 80.68,
"impressions": 11404,
"reach": 4711,
"frequency": 2.42,
"clicks": 111,
"ctr_pct": 0.97,
"average_cpc": 0.73,
"cpm": 7.07,
"purchases": 2,
"purchase_value": 275.69,
"cost_per_purchase": 40.34,
"roas": 3.42,
"leads": 2,
"cost_per_lead": 40.34,
"share_pct": 2.9,
"previous": {
"cost": 81.91,
"impressions": 12567,
"reach": 5092,
"frequency": 2.47,
"clicks": 107,
"ctr_pct": 0.85,
"average_cpc": 0.77,
"cpm": 6.52,
"purchases": 2,
"purchase_value": 253.73,
"cost_per_purchase": 40.96,
"roas": 3.1,
"leads": 2,
"cost_per_lead": 40.96
}
}
],
"meta": {
"site_id": "YOUR_SITE_ID",
"next_cursor": null,
"total": 4,
"period": {
"from": "2026-10-17",
"to": "2026-11-13",
"compare_from": "2026-09-19",
"compare_to": "2026-10-16"
},
"currency": "EUR"
}
}
Response fields · data is a list; each item has:
| Field | Type | What it is |
|---|---|---|
placement | string | facebook, instagram, messenger, audience_network or threads. |
cost | number | Amount spent, in the currency of the ad account (meta.currency). |
impressions | integer | Impressions. |
reach | integer | People reached at least once in the period (counted once however often they saw an ad, so reach does not add up over days or rows). |
frequency | number or null | Impressions per person reached; null without reach. |
clicks | integer | Link clicks (clicks to the website, app or form; not likes, comments or profile clicks). |
ctr_pct | number or null | Link clicks as a share of impressions, 0-100; null without impressions. |
average_cpc | number or null | Cost per link click; null without link clicks. |
cpm | number or null | Cost per 1,000 impressions; null without impressions. |
purchases | number | Purchases attributed to the ads (website, app and shop together, as Meta counts them with the account's attribution setting). |
purchase_value | number | Value of those purchases, in the account currency. |
cost_per_purchase | number or null | Cost per purchase; null without purchases. |
roas | number or null | Return on ad spend: purchase_value divided by cost (3.5 = 3.5 times the cost back); null without cost. |
leads | number | Leads (forms on Facebook and Instagram and leads on the website). |
cost_per_lead | number or null | Cost per lead; null without leads. |
share_pct | number or null | Share of the cost of the whole list, 0-100; null when the list cost nothing. |
previous | object or null | The same figures in the previous period; null when it had no impressions then. |
previous.cost | number | Amount spent, in the currency of the ad account (meta.currency). |
previous.impressions | integer | Impressions. |
previous.reach | integer | People reached at least once in the period (counted once however often they saw an ad, so reach does not add up over days or rows). |
previous.frequency | number or null | Impressions per person reached; null without reach. |
previous.clicks | integer | Link clicks (clicks to the website, app or form; not likes, comments or profile clicks). |
previous.ctr_pct | number or null | Link clicks as a share of impressions, 0-100; null without impressions. |
previous.average_cpc | number or null | Cost per link click; null without link clicks. |
previous.cpm | number or null | Cost per 1,000 impressions; null without impressions. |
previous.purchases | number | Purchases attributed to the ads (website, app and shop together, as Meta counts them with the account's attribution setting). |
previous.purchase_value | number | Value of those purchases, in the account currency. |
previous.cost_per_purchase | number or null | Cost per purchase; null without purchases. |
previous.roas | number or null | Return on ad spend: purchase_value divided by cost (3.5 = 3.5 times the cost back); null without cost. |
previous.leads | number | Leads (forms on Facebook and Instagram and leads on the website). |
previous.cost_per_lead | number or null | Cost per lead; null without leads. |
metaads.devices
POST /rest/v1/metaads.devices · MCP tool get_metaads_devices
Returns the Meta Ads figures of the chosen ad account of one site per device (mobile: in an app or a mobile browser; desktop; other) in the period, most spent first, with the previous period. The period runs up to yesterday at the latest; meta.period gives it and the previous period, meta.currency the account currency (EUR). Fails with 409 not_connected when Meta Ads is not connected for the site (or the connection expired: Meta connections last about 60 days), 409 no_account when no ad account is chosen.
Arguments
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
from | string, YYYY-MM-DD | First day of the period, YYYY-MM-DD; give it together with to. |
to | string, YYYY-MM-DD | Last day of the period, YYYY-MM-DD (yesterday at the latest); give it together with from. At most 366 days. |
days | integer, 1 to 366, default 28 | Without from and to: the last this many days up to yesterday. Defaults to 28. |
compare | one of previous_period, previous_year | What the previous figures are: previous_period (the same number of days just before) or previous_year (the same days 52 weeks earlier, same weekdays; for periods up to 364 days). Defaults to previous_period. |
limit | integer, 1 to 500, default 100 | Items per call. |
cursor | string | meta.next_cursor of the previous call, for the next page. |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/metaads.devices \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"site_id":"YOUR_SITE_ID","days":28}'
Example response · Sample figures of a made-up web shop.
{
"data": [
{
"device": "mobile",
"cost": 2452.86,
"impressions": 330701,
"reach": 136610,
"frequency": 2.42,
"clicks": 3530,
"ctr_pct": 1.07,
"average_cpc": 0.69,
"cpm": 7.42,
"purchases": 92,
"purchase_value": 10979.34,
"cost_per_purchase": 26.66,
"roas": 4.48,
"leads": 83,
"cost_per_lead": 29.55,
"share_pct": 86.8,
"previous": {
"cost": 2490.41,
"impressions": 364434,
"reach": 147681,
"frequency": 2.47,
"clicks": 3404,
"ctr_pct": 0.93,
"average_cpc": 0.73,
"cpm": 6.83,
"purchases": 85,
"purchase_value": 10104.62,
"cost_per_purchase": 29.3,
"roas": 4.06,
"leads": 75,
"cost_per_lead": 33.21
}
},
{
"device": "desktop",
"cost": 372.49,
"impressions": 49415,
"reach": 20413,
"frequency": 2.42,
"clicks": 744,
"ctr_pct": 1.51,
"average_cpc": 0.5,
"cpm": 7.54,
"purchases": 12,
"purchase_value": 1419.97,
"cost_per_purchase": 31.04,
"roas": 3.81,
"leads": 11,
"cost_per_lead": 33.86,
"share_pct": 13.2,
"previous": {
"cost": 378.19,
"impressions": 54456,
"reach": 22067,
"frequency": 2.47,
"clicks": 717,
"ctr_pct": 1.32,
"average_cpc": 0.53,
"cpm": 6.94,
"purchases": 11,
"purchase_value": 1306.84,
"cost_per_purchase": 34.38,
"roas": 3.46,
"leads": 10,
"cost_per_lead": 37.82
}
}
],
"meta": {
"site_id": "YOUR_SITE_ID",
"next_cursor": null,
"total": 2,
"period": {
"from": "2026-10-17",
"to": "2026-11-13",
"compare_from": "2026-09-19",
"compare_to": "2026-10-16"
},
"currency": "EUR"
}
}
Response fields · data is a list; each item has:
| Field | Type | What it is |
|---|---|---|
device | string | mobile, desktop or other. |
cost | number | Amount spent, in the currency of the ad account (meta.currency). |
impressions | integer | Impressions. |
reach | integer | People reached at least once in the period (counted once however often they saw an ad, so reach does not add up over days or rows). |
frequency | number or null | Impressions per person reached; null without reach. |
clicks | integer | Link clicks (clicks to the website, app or form; not likes, comments or profile clicks). |
ctr_pct | number or null | Link clicks as a share of impressions, 0-100; null without impressions. |
average_cpc | number or null | Cost per link click; null without link clicks. |
cpm | number or null | Cost per 1,000 impressions; null without impressions. |
purchases | number | Purchases attributed to the ads (website, app and shop together, as Meta counts them with the account's attribution setting). |
purchase_value | number | Value of those purchases, in the account currency. |
cost_per_purchase | number or null | Cost per purchase; null without purchases. |
roas | number or null | Return on ad spend: purchase_value divided by cost (3.5 = 3.5 times the cost back); null without cost. |
leads | number | Leads (forms on Facebook and Instagram and leads on the website). |
cost_per_lead | number or null | Cost per lead; null without leads. |
share_pct | number or null | Share of the cost of the whole list, 0-100; null when the list cost nothing. |
previous | object or null | The same figures in the previous period; null when it had no impressions then. |
previous.cost | number | Amount spent, in the currency of the ad account (meta.currency). |
previous.impressions | integer | Impressions. |
previous.reach | integer | People reached at least once in the period (counted once however often they saw an ad, so reach does not add up over days or rows). |
previous.frequency | number or null | Impressions per person reached; null without reach. |
previous.clicks | integer | Link clicks (clicks to the website, app or form; not likes, comments or profile clicks). |
previous.ctr_pct | number or null | Link clicks as a share of impressions, 0-100; null without impressions. |
previous.average_cpc | number or null | Cost per link click; null without link clicks. |
previous.cpm | number or null | Cost per 1,000 impressions; null without impressions. |
previous.purchases | number | Purchases attributed to the ads (website, app and shop together, as Meta counts them with the account's attribution setting). |
previous.purchase_value | number | Value of those purchases, in the account currency. |
previous.cost_per_purchase | number or null | Cost per purchase; null without purchases. |
previous.roas | number or null | Return on ad spend: purchase_value divided by cost (3.5 = 3.5 times the cost back); null without cost. |
previous.leads | number | Leads (forms on Facebook and Instagram and leads on the website). |
previous.cost_per_lead | number or null | Cost per lead; null without leads. |
metaads.demographics
POST /rest/v1/metaads.demographics · MCP tool get_metaads_demographics
Returns the Meta Ads figures of the chosen ad account of one site per age group and gender in the period, most spent first, with the previous period. The period runs up to yesterday at the latest; meta.period gives it and the previous period, meta.currency the account currency (EUR). Fails with 409 not_connected when Meta Ads is not connected for the site (or the connection expired: Meta connections last about 60 days), 409 no_account when no ad account is chosen.
Arguments
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
from | string, YYYY-MM-DD | First day of the period, YYYY-MM-DD; give it together with to. |
to | string, YYYY-MM-DD | Last day of the period, YYYY-MM-DD (yesterday at the latest); give it together with from. At most 366 days. |
days | integer, 1 to 366, default 28 | Without from and to: the last this many days up to yesterday. Defaults to 28. |
compare | one of previous_period, previous_year | What the previous figures are: previous_period (the same number of days just before) or previous_year (the same days 52 weeks earlier, same weekdays; for periods up to 364 days). Defaults to previous_period. |
limit | integer, 1 to 500, default 100 | Items per call. |
cursor | string | meta.next_cursor of the previous call, for the next page. |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/metaads.demographics \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"site_id":"YOUR_SITE_ID","days":28,"limit":3}'
Example response · Sample figures of a made-up web shop.
{
"data": [
{
"age": "35-44",
"gender": "female",
"cost": 452.87,
"impressions": 59526,
"reach": 24590,
"frequency": 2.42,
"clicks": 609,
"ctr_pct": 1.02,
"average_cpc": 0.74,
"cpm": 7.61,
"purchases": 15,
"purchase_value": 1787.99,
"cost_per_purchase": 30.19,
"roas": 3.95,
"leads": 13,
"cost_per_lead": 34.84,
"share_pct": 16,
"previous": {
"cost": 459.8,
"impressions": 65598,
"reach": 26583,
"frequency": 2.47,
"clicks": 587,
"ctr_pct": 0.89,
"average_cpc": 0.78,
"cpm": 7.01,
"purchases": 14,
"purchase_value": 1645.54,
"cost_per_purchase": 32.84,
"roas": 3.58,
"leads": 12,
"cost_per_lead": 38.32
}
},
{
"age": "25-34",
"gender": "female",
"cost": 433.07,
"impressions": 63936,
"reach": 26411,
"frequency": 2.42,
"clicks": 609,
"ctr_pct": 0.95,
"average_cpc": 0.71,
"cpm": 6.77,
"purchases": 11,
"purchase_value": 1349.78,
"cost_per_purchase": 39.37,
"roas": 3.12,
"leads": 10,
"cost_per_lead": 43.31,
"share_pct": 15.3,
"previous": {
"cost": 439.7,
"impressions": 70457,
"reach": 28552,
"frequency": 2.47,
"clicks": 588,
"ctr_pct": 0.83,
"average_cpc": 0.75,
"cpm": 6.24,
"purchases": 10,
"purchase_value": 1242.24,
"cost_per_purchase": 43.97,
"roas": 2.83,
"leads": 9,
"cost_per_lead": 48.86
}
},
{
"age": "35-44",
"gender": "male",
"cost": 378.36,
"impressions": 41053,
"reach": 16958,
"frequency": 2.42,
"clicks": 628,
"ctr_pct": 1.53,
"average_cpc": 0.6,
"cpm": 9.22,
"purchases": 13,
"purchase_value": 1523.03,
"cost_per_purchase": 29.1,
"roas": 4.03,
"leads": 11,
"cost_per_lead": 34.4,
"share_pct": 13.4,
"previous": {
"cost": 384.15,
"impressions": 45240,
"reach": 18333,
"frequency": 2.47,
"clicks": 606,
"ctr_pct": 1.34,
"average_cpc": 0.63,
"cpm": 8.49,
"purchases": 12,
"purchase_value": 1401.69,
"cost_per_purchase": 32.01,
"roas": 3.65,
"leads": 10,
"cost_per_lead": 38.42
}
}
],
"meta": {
"site_id": "YOUR_SITE_ID",
"next_cursor": "3",
"total": 18,
"period": {
"from": "2026-10-17",
"to": "2026-11-13",
"compare_from": "2026-09-19",
"compare_to": "2026-10-16"
},
"currency": "EUR"
}
}
Response fields · data is a list; each item has:
| Field | Type | What it is |
|---|---|---|
age | string | The age group: 13-17, 18-24, 25-34, 35-44, 45-54, 55-64, 65+ or unknown. |
gender | string | female, male or unknown. |
cost | number | Amount spent, in the currency of the ad account (meta.currency). |
impressions | integer | Impressions. |
reach | integer | People reached at least once in the period (counted once however often they saw an ad, so reach does not add up over days or rows). |
frequency | number or null | Impressions per person reached; null without reach. |
clicks | integer | Link clicks (clicks to the website, app or form; not likes, comments or profile clicks). |
ctr_pct | number or null | Link clicks as a share of impressions, 0-100; null without impressions. |
average_cpc | number or null | Cost per link click; null without link clicks. |
cpm | number or null | Cost per 1,000 impressions; null without impressions. |
purchases | number | Purchases attributed to the ads (website, app and shop together, as Meta counts them with the account's attribution setting). |
purchase_value | number | Value of those purchases, in the account currency. |
cost_per_purchase | number or null | Cost per purchase; null without purchases. |
roas | number or null | Return on ad spend: purchase_value divided by cost (3.5 = 3.5 times the cost back); null without cost. |
leads | number | Leads (forms on Facebook and Instagram and leads on the website). |
cost_per_lead | number or null | Cost per lead; null without leads. |
share_pct | number or null | Share of the cost of the whole list, 0-100; null when the list cost nothing. |
previous | object or null | The same figures in the previous period; null when it had no impressions then. |
previous.cost | number | Amount spent, in the currency of the ad account (meta.currency). |
previous.impressions | integer | Impressions. |
previous.reach | integer | People reached at least once in the period (counted once however often they saw an ad, so reach does not add up over days or rows). |
previous.frequency | number or null | Impressions per person reached; null without reach. |
previous.clicks | integer | Link clicks (clicks to the website, app or form; not likes, comments or profile clicks). |
previous.ctr_pct | number or null | Link clicks as a share of impressions, 0-100; null without impressions. |
previous.average_cpc | number or null | Cost per link click; null without link clicks. |
previous.cpm | number or null | Cost per 1,000 impressions; null without impressions. |
previous.purchases | number | Purchases attributed to the ads (website, app and shop together, as Meta counts them with the account's attribution setting). |
previous.purchase_value | number | Value of those purchases, in the account currency. |
previous.cost_per_purchase | number or null | Cost per purchase; null without purchases. |
previous.roas | number or null | Return on ad spend: purchase_value divided by cost (3.5 = 3.5 times the cost back); null without cost. |
previous.leads | number | Leads (forms on Facebook and Instagram and leads on the website). |
previous.cost_per_lead | number or null | Cost per lead; null without leads. |
metaads.results
POST /rest/v1/metaads.results · MCP tool get_metaads_results
Returns what people did after seeing the ads of the chosen Meta ad account of one site in the period, per action (purchases, leads, registrations, checkouts started, adds to cart, landing page views, link clicks, video views, …), with the count, the value (for purchases) and the cost per action, against the previous period. Each action is counted once (Meta reports the same purchase under several names). The period runs up to yesterday at the latest; meta.period gives it and the previous period, meta.currency the account currency (EUR). Fails with 409 not_connected when Meta Ads is not connected for the site (or the connection expired: Meta connections last about 60 days), 409 no_account when no ad account is chosen.
Arguments
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
from | string, YYYY-MM-DD | First day of the period, YYYY-MM-DD; give it together with to. |
to | string, YYYY-MM-DD | Last day of the period, YYYY-MM-DD (yesterday at the latest); give it together with from. At most 366 days. |
days | integer, 1 to 366, default 28 | Without from and to: the last this many days up to yesterday. Defaults to 28. |
compare | one of previous_period, previous_year | What the previous figures are: previous_period (the same number of days just before) or previous_year (the same days 52 weeks earlier, same weekdays; for periods up to 364 days). Defaults to previous_period. |
limit | integer, 1 to 500, default 100 | Items per call. |
cursor | string | meta.next_cursor of the previous call, for the next page. |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/metaads.results \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"site_id":"YOUR_SITE_ID","days":28,"limit":4}'
Example response · Sample figures of a made-up web shop.
{
"data": [
{
"action": "purchase",
"name": "Purchases",
"count": 104,
"value": 12399.31,
"cost_per_action": 27.17,
"previous": {"count": 95, "value": 11411.45, "cost_per_action": 30.2}
},
{
"action": "lead",
"name": "Leads",
"count": 93,
"value": 0,
"cost_per_action": 30.38,
"previous": {"count": 85, "value": 0, "cost_per_action": 33.75}
},
{
"action": "initiate_checkout",
"name": "Checkouts started",
"count": 177,
"value": 0,
"cost_per_action": 15.96,
"previous": {"count": 162, "value": 0, "cost_per_action": 17.71}
},
{
"action": "add_to_cart",
"name": "Adds to cart",
"count": 396,
"value": 0,
"cost_per_action": 7.13,
"previous": {"count": 364, "value": 0, "cost_per_action": 7.88}
}
],
"meta": {
"site_id": "YOUR_SITE_ID",
"next_cursor": "4",
"total": 9,
"period": {
"from": "2026-10-17",
"to": "2026-11-13",
"compare_from": "2026-09-19",
"compare_to": "2026-10-16"
},
"currency": "EUR"
}
}
Response fields · data is a list; each item has:
| Field | Type | What it is |
|---|---|---|
action | string | purchase, lead, complete_registration, initiate_checkout, add_payment_info, add_to_cart, view_content, search, contact, subscribe, app_install, landing_page_view, link_click, video_view or post_engagement. |
name | string | The action in plain English. |
count | number | How often, in the period. |
value | number | Their value in the account currency (purchases; 0 for most other actions). |
cost_per_action | number or null | The amount spent in the period divided by the count. |
previous | object or null | The same in the previous period; null when it did not happen then. |
previous.count | number | How often. |
previous.value | number | Their value. |
previous.cost_per_action | number or null | Cost per action. |
metaads.accounts
POST /rest/v1/metaads.accounts · MCP tool get_metaads_accounts
Returns the Meta Ads connection of the site: whether a Facebook user is connected, the chosen ad account, and every ad account that user can read, also through a Business Manager (to choose one with metaads.account_set). accounts is empty when nothing is connected; connected is false when the connection expired.
Arguments
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/metaads.accounts \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"site_id":"YOUR_SITE_ID"}'
Example response ·
{
"data": {
"connected": true,
"account_id": "1234567890",
"accounts": [
{
"account_id": "1234567890",
"name": "Example shop",
"currency": "EUR",
"status": "active",
"business": "Example agency"
},
{
"account_id": "9876543210",
"name": "Example shop (old)",
"currency": "EUR",
"status": "closed",
"business": null
}
]
},
"meta": {"site_id": "YOUR_SITE_ID"}
}
Response fields · in data:
| Field | Type | What it is |
|---|---|---|
connected | boolean | Whether a Facebook user with ads access is connected (and the connection still works). |
account_id | string or null | The chosen ad account, digits only; null when none is chosen. |
accounts | array | The ad accounts the connected user can read. |
accounts[].account_id | string | The ad account id, digits only. |
accounts[].name | string | Its name in Meta. |
accounts[].currency | string or null | Its currency (EUR). |
accounts[].status | string or null | active, disabled, unsettled, in_grace_period, closed, … |
accounts[].business | string or null | The Business Manager it belongs to; null when it belongs to the person. |
metaads.account_set
POST /rest/v1/metaads.account_set · MCP tool
Returns the chosen ad account after choosing the Meta ad account of the site, one of the accounts the connected Facebook user can read (metaads.accounts). Anyone on the site may do this, guests too (connecting is for everyone).
Arguments
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
account_id (required) | string | The ad account id from metaads.accounts (act_ in front is fine). |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/metaads.account_set \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"site_id":"YOUR_SITE_ID","account_id":"act_1234567890"}'
Example response ·
{
"data": {"account_id": "1234567890", "name": "Example shop", "currency": "EUR"},
"meta": {"site_id": "YOUR_SITE_ID"}
}
Response fields · in data:
| Field | Type | What it is |
|---|---|---|
account_id | string | The ad account now in use, digits only. |
name | string | Its name in Meta. |
currency | string or null | Its currency. |
metaads.disconnect
POST /rest/v1/metaads.disconnect · MCP tool
Returns connected false after disconnecting Meta Ads from the site (the Facebook user and the chosen ad account). Anyone on the site may do this, like connecting.
Arguments
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/metaads.disconnect \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"site_id":"YOUR_SITE_ID"}'
Example response · Disconnecting always answers this.
{"data": {"connected": false}, "meta": {"site_id": "YOUR_SITE_ID"}}
Response fields · in data:
| Field | Type | What it is |
|---|---|---|
connected | boolean | Always false. |
Every client's Meta Ads under your own domain. One white-label key for all your sites.
Build your own agency portal or client report on our backend. On your custom white-label domain, the REST API and the MCP server answer under your hostname and brand. One white-label key (mtw_…) gives you 600 calls a minute across every client site in your account. Clients who sign in to the MCP see your agency's name and logo.
Free 14-day trial
MarketingTracer smart A.I. tool shows you what you need to rank. Then we'll help you get it done.
- No credit card required
- No installation needed
- No strings attached
FAQ
Something else? Ask us.
How do I connect a client's Meta ad account?
Log in with Facebook once on the Meta Ads page of the site in MarketingTracer. The login asks only for ads_read and public_profile so we can read ad reports. After that, you pick the ad account in the app or through the REST API with metaads.accounts and metaads.account_set. Business Manager accounts are included too.
Can the API or MCP change budgets, bids or ads in Meta?
No. The connection is strictly for reporting. Neither the REST API nor the MCP can create or edit campaigns, ad sets, ads, budgets or audiences in Meta Ads.
Why are reach and frequency missing from metaads.daily?
Daily reach figures cannot be summed into a period total. Reach counts each person who saw an ad at least once during the period. Someone who sees an ad on Tuesday and again on Thursday counts as one reached person for the month. Use metaads.summary, metaads.campaigns or the breakdown endpoints for the true period reach and frequency.
How does the API avoid double-counting purchases and leads?
Our endpoints take the primary action count for each conversion type so every purchase, lead or checkout is counted once. Meta's Graph API returns the same conversion under several action names, such as omni_purchase, purchase and onsite_web_purchase.
What happens when a Meta connection expires?
When the 60-day Meta access token expires or is revoked, the reporting endpoints return HTTP 409 with error code not_connected. A call to metaads.accounts returns "connected": false. Log in with Facebook again on the site's Meta Ads page in MarketingTracer to renew it.
What errors can the Meta Ads endpoints return?
The API returns 409 not_connected when Meta Ads is not connected for the site or the 60-day login has expired. If a Facebook user is connected but no ad account has been selected yet, it returns 409 no_account. When Meta's Graph API fails or times out, it returns 502 meta_error.
Is the Meta Ads API included in my plan, and what is the rate limit?
Yes, every MarketingTracer plan includes the REST API and the MCP server at no extra cost. A personal key (mtk_…) allows 60 calls per minute, and a white-label key (mtw_…) allows 600 calls per minute across the API and MCP together.