NEWAI content checker: see which pages read like AI text

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"
  }
}
Client reporting

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.

Campaign drill-down

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.

Funnel and MCP

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

ArgumentTypeWhat it does
site_id (required)stringThe site: its id from list_sites, or the id in the app’s address.
fromstring, YYYY-MM-DDFirst day of the period, YYYY-MM-DD; give it together with to.
tostring, YYYY-MM-DDLast day of the period, YYYY-MM-DD (yesterday at the latest); give it together with from. At most 366 days.
daysinteger, 1 to 366, default 28Without from and to: the last this many days up to yesterday. Defaults to 28.
compareone of previous_period, previous_yearWhat 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:

FieldTypeWhat it is
comparestringprevious_period or previous_year: what the previous figures are.
costobjectAmount spent in the period, against the previous period.
cost.valuenumber or nullThis period; null when it does not apply.
cost.previousnumber or nullThe previous period; null when it does not apply.
cost.changenumber or nullvalue minus previous.
cost.change_pctnumber or nullThe change in percent of previous; null when previous is 0 or null.
impressionsobjectImpressions in the period, against the previous period.
impressions.valuenumber or nullThis period; null when it does not apply.
impressions.previousnumber or nullThe previous period; null when it does not apply.
impressions.changenumber or nullvalue minus previous.
impressions.change_pctnumber or nullThe change in percent of previous; null when previous is 0 or null.
reachobjectPeople reached in the period, against the previous period.
reach.valuenumber or nullThis period; null when it does not apply.
reach.previousnumber or nullThe previous period; null when it does not apply.
reach.changenumber or nullvalue minus previous.
reach.change_pctnumber or nullThe change in percent of previous; null when previous is 0 or null.
frequencyobjectImpressions per person reached in the period, against the previous period.
frequency.valuenumber or nullThis period; null when it does not apply.
frequency.previousnumber or nullThe previous period; null when it does not apply.
frequency.changenumber or nullvalue minus previous.
frequency.change_pctnumber or nullThe change in percent of previous; null when previous is 0 or null.
clicksobjectLink clicks in the period, against the previous period.
clicks.valuenumber or nullThis period; null when it does not apply.
clicks.previousnumber or nullThe previous period; null when it does not apply.
clicks.changenumber or nullvalue minus previous.
clicks.change_pctnumber or nullThe change in percent of previous; null when previous is 0 or null.
ctr_pctobjectLink CTR, 0-100, in the period, against the previous period.
ctr_pct.valuenumber or nullThis period; null when it does not apply.
ctr_pct.previousnumber or nullThe previous period; null when it does not apply.
ctr_pct.changenumber or nullvalue minus previous, in percentage points.
ctr_pct.change_pctnumber or nullThe change in percent of previous; null when previous is 0 or null.
average_cpcobjectCost per link click in the period, against the previous period.
average_cpc.valuenumber or nullThis period; null when it does not apply.
average_cpc.previousnumber or nullThe previous period; null when it does not apply.
average_cpc.changenumber or nullvalue minus previous.
average_cpc.change_pctnumber or nullThe change in percent of previous; null when previous is 0 or null.
cpmobjectCost per 1,000 impressions in the period, against the previous period.
cpm.valuenumber or nullThis period; null when it does not apply.
cpm.previousnumber or nullThe previous period; null when it does not apply.
cpm.changenumber or nullvalue minus previous.
cpm.change_pctnumber or nullThe change in percent of previous; null when previous is 0 or null.
purchasesobjectPurchases in the period, against the previous period.
purchases.valuenumber or nullThis period; null when it does not apply.
purchases.previousnumber or nullThe previous period; null when it does not apply.
purchases.changenumber or nullvalue minus previous.
purchases.change_pctnumber or nullThe change in percent of previous; null when previous is 0 or null.
purchase_valueobjectPurchase value in the period, against the previous period.
purchase_value.valuenumber or nullThis period; null when it does not apply.
purchase_value.previousnumber or nullThe previous period; null when it does not apply.
purchase_value.changenumber or nullvalue minus previous.
purchase_value.change_pctnumber or nullThe change in percent of previous; null when previous is 0 or null.
cost_per_purchaseobjectCost per purchase in the period, against the previous period.
cost_per_purchase.valuenumber or nullThis period; null when it does not apply.
cost_per_purchase.previousnumber or nullThe previous period; null when it does not apply.
cost_per_purchase.changenumber or nullvalue minus previous.
cost_per_purchase.change_pctnumber or nullThe change in percent of previous; null when previous is 0 or null.
roasobjectROAS (purchase value / cost) in the period, against the previous period.
roas.valuenumber or nullThis period; null when it does not apply.
roas.previousnumber or nullThe previous period; null when it does not apply.
roas.changenumber or nullvalue minus previous.
roas.change_pctnumber or nullThe change in percent of previous; null when previous is 0 or null.
leadsobjectLeads in the period, against the previous period.
leads.valuenumber or nullThis period; null when it does not apply.
leads.previousnumber or nullThe previous period; null when it does not apply.
leads.changenumber or nullvalue minus previous.
leads.change_pctnumber or nullThe change in percent of previous; null when previous is 0 or null.
cost_per_leadobjectCost per lead in the period, against the previous period.
cost_per_lead.valuenumber or nullThis period; null when it does not apply.
cost_per_lead.previousnumber or nullThe previous period; null when it does not apply.
cost_per_lead.changenumber or nullvalue minus previous.
cost_per_lead.change_pctnumber or nullThe 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

ArgumentTypeWhat it does
site_id (required)stringThe site: its id from list_sites, or the id in the app’s address.
fromstring, YYYY-MM-DDFirst day of the period, YYYY-MM-DD; give it together with to.
tostring, YYYY-MM-DDLast day of the period, YYYY-MM-DD (yesterday at the latest); give it together with from. At most 366 days.
daysinteger, 1 to 366, default 28Without from and to: the last this many days up to yesterday. Defaults to 28.
compareone of previous_period, previous_yearWhat 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:

FieldTypeWhat it is
comparestringprevious_period or previous_year: what the previous figures are.
daysarrayPer day of the period, oldest first.
days[].datestringThe day, YYYY-MM-DD.
days[].costnumberAmount spent, in the currency of the ad account (meta.currency).
days[].impressionsintegerImpressions.
days[].clicksintegerLink clicks (clicks to the website, app or form; not likes, comments or profile clicks).
days[].ctr_pctnumber or nullLink clicks as a share of impressions, 0-100; null without impressions.
days[].average_cpcnumber or nullCost per link click; null without link clicks.
days[].cpmnumber or nullCost per 1,000 impressions; null without impressions.
days[].purchasesnumberPurchases attributed to the ads (website, app and shop together, as Meta counts them with the account's attribution setting).
days[].purchase_valuenumberValue of those purchases, in the account currency.
days[].cost_per_purchasenumber or nullCost per purchase; null without purchases.
days[].roasnumber or nullReturn on ad spend: purchase_value divided by cost (3.5 = 3.5 times the cost back); null without cost.
days[].leadsnumberLeads (forms on Facebook and Instagram and leads on the website).
days[].cost_per_leadnumber or nullCost per lead; null without leads.
days[].previous_datestringThe matching day of the previous period, YYYY-MM-DD.
days[].previousobjectThe same figures on previous_date.
days[].previous.costnumberAmount spent, in the currency of the ad account (meta.currency).
days[].previous.impressionsintegerImpressions.
days[].previous.clicksintegerLink clicks (clicks to the website, app or form; not likes, comments or profile clicks).
days[].previous.ctr_pctnumber or nullLink clicks as a share of impressions, 0-100; null without impressions.
days[].previous.average_cpcnumber or nullCost per link click; null without link clicks.
days[].previous.cpmnumber or nullCost per 1,000 impressions; null without impressions.
days[].previous.purchasesnumberPurchases attributed to the ads (website, app and shop together, as Meta counts them with the account's attribution setting).
days[].previous.purchase_valuenumberValue of those purchases, in the account currency.
days[].previous.cost_per_purchasenumber or nullCost per purchase; null without purchases.
days[].previous.roasnumber or nullReturn on ad spend: purchase_value divided by cost (3.5 = 3.5 times the cost back); null without cost.
days[].previous.leadsnumberLeads (forms on Facebook and Instagram and leads on the website).
days[].previous.cost_per_leadnumber or nullCost 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

ArgumentTypeWhat it does
site_id (required)stringThe site: its id from list_sites, or the id in the app’s address.
fromstring, YYYY-MM-DDFirst day of the period, YYYY-MM-DD; give it together with to.
tostring, YYYY-MM-DDLast day of the period, YYYY-MM-DD (yesterday at the latest); give it together with from. At most 366 days.
daysinteger, 1 to 366, default 28Without from and to: the last this many days up to yesterday. Defaults to 28.
compareone of previous_period, previous_yearWhat 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.
limitinteger, 1 to 500, default 100Items per call.
cursorstringmeta.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:

FieldTypeWhat it is
campaign_idstringThe campaign id in Meta.
campaignstringThe campaign name.
statusstring or nullIts delivery status now (not in the period): active, paused, campaign_paused, adset_paused, archived, in_process, with_issues, …
objectivestring or nullWhat the campaign is set to achieve: sales, leads, traffic, awareness, engagement or app_promotion (older objectives are mapped).
daily_budgetnumber or nullThe 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_budgetnumber or nullThe lifetime budget of the campaign now; null when it has none.
costnumberAmount spent, in the currency of the ad account (meta.currency).
impressionsintegerImpressions.
reachintegerPeople 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).
frequencynumber or nullImpressions per person reached; null without reach.
clicksintegerLink clicks (clicks to the website, app or form; not likes, comments or profile clicks).
ctr_pctnumber or nullLink clicks as a share of impressions, 0-100; null without impressions.
average_cpcnumber or nullCost per link click; null without link clicks.
cpmnumber or nullCost per 1,000 impressions; null without impressions.
purchasesnumberPurchases attributed to the ads (website, app and shop together, as Meta counts them with the account's attribution setting).
purchase_valuenumberValue of those purchases, in the account currency.
cost_per_purchasenumber or nullCost per purchase; null without purchases.
roasnumber or nullReturn on ad spend: purchase_value divided by cost (3.5 = 3.5 times the cost back); null without cost.
leadsnumberLeads (forms on Facebook and Instagram and leads on the website).
cost_per_leadnumber or nullCost per lead; null without leads.
share_pctnumber or nullShare of the cost of the whole list, 0-100; null when the list cost nothing.
previousobject or nullThe same figures in the previous period; null when it had no impressions then.
previous.costnumberAmount spent, in the currency of the ad account (meta.currency).
previous.impressionsintegerImpressions.
previous.reachintegerPeople 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.frequencynumber or nullImpressions per person reached; null without reach.
previous.clicksintegerLink clicks (clicks to the website, app or form; not likes, comments or profile clicks).
previous.ctr_pctnumber or nullLink clicks as a share of impressions, 0-100; null without impressions.
previous.average_cpcnumber or nullCost per link click; null without link clicks.
previous.cpmnumber or nullCost per 1,000 impressions; null without impressions.
previous.purchasesnumberPurchases attributed to the ads (website, app and shop together, as Meta counts them with the account's attribution setting).
previous.purchase_valuenumberValue of those purchases, in the account currency.
previous.cost_per_purchasenumber or nullCost per purchase; null without purchases.
previous.roasnumber or nullReturn on ad spend: purchase_value divided by cost (3.5 = 3.5 times the cost back); null without cost.
previous.leadsnumberLeads (forms on Facebook and Instagram and leads on the website).
previous.cost_per_leadnumber or nullCost 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

ArgumentTypeWhat it does
site_id (required)stringThe site: its id from list_sites, or the id in the app’s address.
fromstring, YYYY-MM-DDFirst day of the period, YYYY-MM-DD; give it together with to.
tostring, YYYY-MM-DDLast day of the period, YYYY-MM-DD (yesterday at the latest); give it together with from. At most 366 days.
daysinteger, 1 to 366, default 28Without from and to: the last this many days up to yesterday. Defaults to 28.
compareone of previous_period, previous_yearWhat 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_idstringOnly this campaign (its campaign_id from metaads.campaigns).
limitinteger, 1 to 500, default 100Items per call.
cursorstringmeta.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:

FieldTypeWhat it is
adset_idstringThe ad set id in Meta.
adsetstringThe ad set name.
statusstring or nullIts delivery status now (not in the period): active, paused, campaign_paused, adset_paused, archived, in_process, with_issues, …
daily_budgetnumber or nullThe daily budget of the ad set now; null when the campaign holds the budget.
lifetime_budgetnumber or nullThe lifetime budget of the ad set now; null when it has none.
campaign_idstringIts campaign.
campaignstringThe campaign name.
costnumberAmount spent, in the currency of the ad account (meta.currency).
impressionsintegerImpressions.
reachintegerPeople 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).
frequencynumber or nullImpressions per person reached; null without reach.
clicksintegerLink clicks (clicks to the website, app or form; not likes, comments or profile clicks).
ctr_pctnumber or nullLink clicks as a share of impressions, 0-100; null without impressions.
average_cpcnumber or nullCost per link click; null without link clicks.
cpmnumber or nullCost per 1,000 impressions; null without impressions.
purchasesnumberPurchases attributed to the ads (website, app and shop together, as Meta counts them with the account's attribution setting).
purchase_valuenumberValue of those purchases, in the account currency.
cost_per_purchasenumber or nullCost per purchase; null without purchases.
roasnumber or nullReturn on ad spend: purchase_value divided by cost (3.5 = 3.5 times the cost back); null without cost.
leadsnumberLeads (forms on Facebook and Instagram and leads on the website).
cost_per_leadnumber or nullCost per lead; null without leads.
share_pctnumber or nullShare of the cost of the whole list, 0-100; null when the list cost nothing.
previousobject or nullThe same figures in the previous period; null when it had no impressions then.
previous.costnumberAmount spent, in the currency of the ad account (meta.currency).
previous.impressionsintegerImpressions.
previous.reachintegerPeople 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.frequencynumber or nullImpressions per person reached; null without reach.
previous.clicksintegerLink clicks (clicks to the website, app or form; not likes, comments or profile clicks).
previous.ctr_pctnumber or nullLink clicks as a share of impressions, 0-100; null without impressions.
previous.average_cpcnumber or nullCost per link click; null without link clicks.
previous.cpmnumber or nullCost per 1,000 impressions; null without impressions.
previous.purchasesnumberPurchases attributed to the ads (website, app and shop together, as Meta counts them with the account's attribution setting).
previous.purchase_valuenumberValue of those purchases, in the account currency.
previous.cost_per_purchasenumber or nullCost per purchase; null without purchases.
previous.roasnumber or nullReturn on ad spend: purchase_value divided by cost (3.5 = 3.5 times the cost back); null without cost.
previous.leadsnumberLeads (forms on Facebook and Instagram and leads on the website).
previous.cost_per_leadnumber or nullCost 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

ArgumentTypeWhat it does
site_id (required)stringThe site: its id from list_sites, or the id in the app’s address.
fromstring, YYYY-MM-DDFirst day of the period, YYYY-MM-DD; give it together with to.
tostring, YYYY-MM-DDLast day of the period, YYYY-MM-DD (yesterday at the latest); give it together with from. At most 366 days.
daysinteger, 1 to 366, default 28Without from and to: the last this many days up to yesterday. Defaults to 28.
compareone of previous_period, previous_yearWhat 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_idstringOnly this campaign (its campaign_id from metaads.campaigns).
adset_idstringOnly this ad set (its adset_id from metaads.adsets).
limitinteger, 1 to 500, default 100Items per call.
cursorstringmeta.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:

FieldTypeWhat it is
ad_idstringThe ad id in Meta.
adstringThe ad name.
statusstring or nullIts delivery status now (not in the period): active, paused, campaign_paused, adset_paused, archived, in_process, with_issues, …
adset_idstringIts ad set.
adsetstringThe ad set name.
campaign_idstringIts campaign.
campaignstringThe campaign name.
costnumberAmount spent, in the currency of the ad account (meta.currency).
impressionsintegerImpressions.
reachintegerPeople 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).
frequencynumber or nullImpressions per person reached; null without reach.
clicksintegerLink clicks (clicks to the website, app or form; not likes, comments or profile clicks).
ctr_pctnumber or nullLink clicks as a share of impressions, 0-100; null without impressions.
average_cpcnumber or nullCost per link click; null without link clicks.
cpmnumber or nullCost per 1,000 impressions; null without impressions.
purchasesnumberPurchases attributed to the ads (website, app and shop together, as Meta counts them with the account's attribution setting).
purchase_valuenumberValue of those purchases, in the account currency.
cost_per_purchasenumber or nullCost per purchase; null without purchases.
roasnumber or nullReturn on ad spend: purchase_value divided by cost (3.5 = 3.5 times the cost back); null without cost.
leadsnumberLeads (forms on Facebook and Instagram and leads on the website).
cost_per_leadnumber or nullCost per lead; null without leads.
share_pctnumber or nullShare of the cost of the whole list, 0-100; null when the list cost nothing.
previousobject or nullThe same figures in the previous period; null when it had no impressions then.
previous.costnumberAmount spent, in the currency of the ad account (meta.currency).
previous.impressionsintegerImpressions.
previous.reachintegerPeople 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.frequencynumber or nullImpressions per person reached; null without reach.
previous.clicksintegerLink clicks (clicks to the website, app or form; not likes, comments or profile clicks).
previous.ctr_pctnumber or nullLink clicks as a share of impressions, 0-100; null without impressions.
previous.average_cpcnumber or nullCost per link click; null without link clicks.
previous.cpmnumber or nullCost per 1,000 impressions; null without impressions.
previous.purchasesnumberPurchases attributed to the ads (website, app and shop together, as Meta counts them with the account's attribution setting).
previous.purchase_valuenumberValue of those purchases, in the account currency.
previous.cost_per_purchasenumber or nullCost per purchase; null without purchases.
previous.roasnumber or nullReturn on ad spend: purchase_value divided by cost (3.5 = 3.5 times the cost back); null without cost.
previous.leadsnumberLeads (forms on Facebook and Instagram and leads on the website).
previous.cost_per_leadnumber or nullCost 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

ArgumentTypeWhat it does
site_id (required)stringThe site: its id from list_sites, or the id in the app’s address.
fromstring, YYYY-MM-DDFirst day of the period, YYYY-MM-DD; give it together with to.
tostring, YYYY-MM-DDLast day of the period, YYYY-MM-DD (yesterday at the latest); give it together with from. At most 366 days.
daysinteger, 1 to 366, default 28Without from and to: the last this many days up to yesterday. Defaults to 28.
compareone of previous_period, previous_yearWhat 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.
limitinteger, 1 to 500, default 100Items per call.
cursorstringmeta.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:

FieldTypeWhat it is
placementstringfacebook, instagram, messenger, audience_network or threads.
costnumberAmount spent, in the currency of the ad account (meta.currency).
impressionsintegerImpressions.
reachintegerPeople 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).
frequencynumber or nullImpressions per person reached; null without reach.
clicksintegerLink clicks (clicks to the website, app or form; not likes, comments or profile clicks).
ctr_pctnumber or nullLink clicks as a share of impressions, 0-100; null without impressions.
average_cpcnumber or nullCost per link click; null without link clicks.
cpmnumber or nullCost per 1,000 impressions; null without impressions.
purchasesnumberPurchases attributed to the ads (website, app and shop together, as Meta counts them with the account's attribution setting).
purchase_valuenumberValue of those purchases, in the account currency.
cost_per_purchasenumber or nullCost per purchase; null without purchases.
roasnumber or nullReturn on ad spend: purchase_value divided by cost (3.5 = 3.5 times the cost back); null without cost.
leadsnumberLeads (forms on Facebook and Instagram and leads on the website).
cost_per_leadnumber or nullCost per lead; null without leads.
share_pctnumber or nullShare of the cost of the whole list, 0-100; null when the list cost nothing.
previousobject or nullThe same figures in the previous period; null when it had no impressions then.
previous.costnumberAmount spent, in the currency of the ad account (meta.currency).
previous.impressionsintegerImpressions.
previous.reachintegerPeople 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.frequencynumber or nullImpressions per person reached; null without reach.
previous.clicksintegerLink clicks (clicks to the website, app or form; not likes, comments or profile clicks).
previous.ctr_pctnumber or nullLink clicks as a share of impressions, 0-100; null without impressions.
previous.average_cpcnumber or nullCost per link click; null without link clicks.
previous.cpmnumber or nullCost per 1,000 impressions; null without impressions.
previous.purchasesnumberPurchases attributed to the ads (website, app and shop together, as Meta counts them with the account's attribution setting).
previous.purchase_valuenumberValue of those purchases, in the account currency.
previous.cost_per_purchasenumber or nullCost per purchase; null without purchases.
previous.roasnumber or nullReturn on ad spend: purchase_value divided by cost (3.5 = 3.5 times the cost back); null without cost.
previous.leadsnumberLeads (forms on Facebook and Instagram and leads on the website).
previous.cost_per_leadnumber or nullCost 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

ArgumentTypeWhat it does
site_id (required)stringThe site: its id from list_sites, or the id in the app’s address.
fromstring, YYYY-MM-DDFirst day of the period, YYYY-MM-DD; give it together with to.
tostring, YYYY-MM-DDLast day of the period, YYYY-MM-DD (yesterday at the latest); give it together with from. At most 366 days.
daysinteger, 1 to 366, default 28Without from and to: the last this many days up to yesterday. Defaults to 28.
compareone of previous_period, previous_yearWhat 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.
limitinteger, 1 to 500, default 100Items per call.
cursorstringmeta.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:

FieldTypeWhat it is
devicestringmobile, desktop or other.
costnumberAmount spent, in the currency of the ad account (meta.currency).
impressionsintegerImpressions.
reachintegerPeople 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).
frequencynumber or nullImpressions per person reached; null without reach.
clicksintegerLink clicks (clicks to the website, app or form; not likes, comments or profile clicks).
ctr_pctnumber or nullLink clicks as a share of impressions, 0-100; null without impressions.
average_cpcnumber or nullCost per link click; null without link clicks.
cpmnumber or nullCost per 1,000 impressions; null without impressions.
purchasesnumberPurchases attributed to the ads (website, app and shop together, as Meta counts them with the account's attribution setting).
purchase_valuenumberValue of those purchases, in the account currency.
cost_per_purchasenumber or nullCost per purchase; null without purchases.
roasnumber or nullReturn on ad spend: purchase_value divided by cost (3.5 = 3.5 times the cost back); null without cost.
leadsnumberLeads (forms on Facebook and Instagram and leads on the website).
cost_per_leadnumber or nullCost per lead; null without leads.
share_pctnumber or nullShare of the cost of the whole list, 0-100; null when the list cost nothing.
previousobject or nullThe same figures in the previous period; null when it had no impressions then.
previous.costnumberAmount spent, in the currency of the ad account (meta.currency).
previous.impressionsintegerImpressions.
previous.reachintegerPeople 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.frequencynumber or nullImpressions per person reached; null without reach.
previous.clicksintegerLink clicks (clicks to the website, app or form; not likes, comments or profile clicks).
previous.ctr_pctnumber or nullLink clicks as a share of impressions, 0-100; null without impressions.
previous.average_cpcnumber or nullCost per link click; null without link clicks.
previous.cpmnumber or nullCost per 1,000 impressions; null without impressions.
previous.purchasesnumberPurchases attributed to the ads (website, app and shop together, as Meta counts them with the account's attribution setting).
previous.purchase_valuenumberValue of those purchases, in the account currency.
previous.cost_per_purchasenumber or nullCost per purchase; null without purchases.
previous.roasnumber or nullReturn on ad spend: purchase_value divided by cost (3.5 = 3.5 times the cost back); null without cost.
previous.leadsnumberLeads (forms on Facebook and Instagram and leads on the website).
previous.cost_per_leadnumber or nullCost 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

ArgumentTypeWhat it does
site_id (required)stringThe site: its id from list_sites, or the id in the app’s address.
fromstring, YYYY-MM-DDFirst day of the period, YYYY-MM-DD; give it together with to.
tostring, YYYY-MM-DDLast day of the period, YYYY-MM-DD (yesterday at the latest); give it together with from. At most 366 days.
daysinteger, 1 to 366, default 28Without from and to: the last this many days up to yesterday. Defaults to 28.
compareone of previous_period, previous_yearWhat 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.
limitinteger, 1 to 500, default 100Items per call.
cursorstringmeta.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:

FieldTypeWhat it is
agestringThe age group: 13-17, 18-24, 25-34, 35-44, 45-54, 55-64, 65+ or unknown.
genderstringfemale, male or unknown.
costnumberAmount spent, in the currency of the ad account (meta.currency).
impressionsintegerImpressions.
reachintegerPeople 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).
frequencynumber or nullImpressions per person reached; null without reach.
clicksintegerLink clicks (clicks to the website, app or form; not likes, comments or profile clicks).
ctr_pctnumber or nullLink clicks as a share of impressions, 0-100; null without impressions.
average_cpcnumber or nullCost per link click; null without link clicks.
cpmnumber or nullCost per 1,000 impressions; null without impressions.
purchasesnumberPurchases attributed to the ads (website, app and shop together, as Meta counts them with the account's attribution setting).
purchase_valuenumberValue of those purchases, in the account currency.
cost_per_purchasenumber or nullCost per purchase; null without purchases.
roasnumber or nullReturn on ad spend: purchase_value divided by cost (3.5 = 3.5 times the cost back); null without cost.
leadsnumberLeads (forms on Facebook and Instagram and leads on the website).
cost_per_leadnumber or nullCost per lead; null without leads.
share_pctnumber or nullShare of the cost of the whole list, 0-100; null when the list cost nothing.
previousobject or nullThe same figures in the previous period; null when it had no impressions then.
previous.costnumberAmount spent, in the currency of the ad account (meta.currency).
previous.impressionsintegerImpressions.
previous.reachintegerPeople 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.frequencynumber or nullImpressions per person reached; null without reach.
previous.clicksintegerLink clicks (clicks to the website, app or form; not likes, comments or profile clicks).
previous.ctr_pctnumber or nullLink clicks as a share of impressions, 0-100; null without impressions.
previous.average_cpcnumber or nullCost per link click; null without link clicks.
previous.cpmnumber or nullCost per 1,000 impressions; null without impressions.
previous.purchasesnumberPurchases attributed to the ads (website, app and shop together, as Meta counts them with the account's attribution setting).
previous.purchase_valuenumberValue of those purchases, in the account currency.
previous.cost_per_purchasenumber or nullCost per purchase; null without purchases.
previous.roasnumber or nullReturn on ad spend: purchase_value divided by cost (3.5 = 3.5 times the cost back); null without cost.
previous.leadsnumberLeads (forms on Facebook and Instagram and leads on the website).
previous.cost_per_leadnumber or nullCost 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

ArgumentTypeWhat it does
site_id (required)stringThe site: its id from list_sites, or the id in the app’s address.
fromstring, YYYY-MM-DDFirst day of the period, YYYY-MM-DD; give it together with to.
tostring, YYYY-MM-DDLast day of the period, YYYY-MM-DD (yesterday at the latest); give it together with from. At most 366 days.
daysinteger, 1 to 366, default 28Without from and to: the last this many days up to yesterday. Defaults to 28.
compareone of previous_period, previous_yearWhat 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.
limitinteger, 1 to 500, default 100Items per call.
cursorstringmeta.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:

FieldTypeWhat it is
actionstringpurchase, 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.
namestringThe action in plain English.
countnumberHow often, in the period.
valuenumberTheir value in the account currency (purchases; 0 for most other actions).
cost_per_actionnumber or nullThe amount spent in the period divided by the count.
previousobject or nullThe same in the previous period; null when it did not happen then.
previous.countnumberHow often.
previous.valuenumberTheir value.
previous.cost_per_actionnumber or nullCost 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

ArgumentTypeWhat it does
site_id (required)stringThe 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:

FieldTypeWhat it is
connectedbooleanWhether a Facebook user with ads access is connected (and the connection still works).
account_idstring or nullThe chosen ad account, digits only; null when none is chosen.
accountsarrayThe ad accounts the connected user can read.
accounts[].account_idstringThe ad account id, digits only.
accounts[].namestringIts name in Meta.
accounts[].currencystring or nullIts currency (EUR).
accounts[].statusstring or nullactive, disabled, unsettled, in_grace_period, closed, …
accounts[].businessstring or nullThe 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

ArgumentTypeWhat it does
site_id (required)stringThe site: its id from list_sites, or the id in the app’s address.
account_id (required)stringThe 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:

FieldTypeWhat it is
account_idstringThe ad account now in use, digits only.
namestringIts name in Meta.
currencystring or nullIts 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

ArgumentTypeWhat it does
site_id (required)stringThe 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:

FieldTypeWhat it is
connectedbooleanAlways false.
White label / agency

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.

API & MCPGoogle Ads API API & MCPGoogle Analytics 4 API MCP serverSEO MCP for Claude, ChatGPT and Cursor

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
Start your 14-day trial

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.