NEWAI content checker: see which pages read like AI text

API/Google Ads

Google Ads API. Paid search next to your organic data.

Read campaigns, search terms, keywords, conversions and ad spend for every client site through our REST API and MCP server, right next to Search Console and GA4. Access is in every plan at no extra cost. We keep the Google Ads connection running in the background while you build your dashboard or client report.

Campaign impression share

Daily budgets, status, channel types and the share of Search impressions each campaign captured or lost to budget or ad rank.

Keywords and queries

The search terms people typed to trigger an ad next to the keywords you bid on, with match type and quality score from 1 to 10.

Reporting only

Reads performance in the account's own currency and never changes a bid, budget or ad in Google Ads.

In every plan

REST endpoints and MCP tools included at no extra cost, with 60 calls per minute on a personal key and 600 on a white label key.

Google Ads endpoints and MCP tools

Once a Google Ads account is connected for a site, eight read endpoints return its numbers through the REST API and as get_googleads_* tools in the MCP server. Two write endpoints let you select the active Google Ads account or disconnect it through the REST API.

Every report endpoint takes a period up to yesterday. Pass days (1 to 366, default 28) or a custom from and to date (YYYY-MM-DD). Set compare to previous_period for the preceding window of the same length, or to previous_year for the same 52-week-earlier weekdays on ranges up to 364 days. List endpoints page with limit (1 to 500, default 100) and cursor from meta.next_cursor. All money figures use the Google Ads account's own currency in meta.currency.

Endpoint MCP tool What you get
googleads.summary get_googleads_summary Account totals for all 11 metrics (clicks, impressions, CTR, cost, average CPC, conversions, conversion rate, cost per conversion, conversion value, ROAS and absolute top impression share), each with value and previous plus change and change_pct. Also includes daily rows for every day in the period next to the matching comparison day.
googleads.campaigns get_googleads_campaigns Campaigns with impressions in the period, sorted by clicks. Includes campaign status, channel_type, daily_budget, click share_pct, the 11 metrics with previous figures, and Search impression share for Search and Shopping (search_impression_share_pct, search_lost_budget_pct and search_lost_rank_pct).
googleads.ad_groups get_googleads_ad_groups Ad-group performance for the period, sorted by clicks, with ad_group_id, ad_group, current status, parent campaign_id, campaign, click share_pct and all 11 metrics with previous. Performance Max campaigns have no ad groups.
googleads.search_terms get_googleads_search_terms The search queries people typed when an ad appeared, summed across ad groups and sorted by clicks. Each row includes click share_pct along with all 11 metrics and previous period totals for up to the 5,000 queries with the most impressions (Google omits rare queries for privacy).
googleads.keywords get_googleads_keywords Up to 5,000 bidded keywords with impressions in the period, sorted by clicks. Gives each keyword's match_type, current status, quality_score (1 to 10), parent ad group and campaign, click share_pct, and all 11 metrics with previous figures.
googleads.devices get_googleads_devices Splits performance across the five device types (mobile, desktop, tablet, connected_tv or other), sorted by clicks, with click share_pct plus all 11 metrics and their previous values.
googleads.conversions get_googleads_conversions Totals per conversion_action (such as purchases or lead forms), sorted by conversions. Gives primary conversions and conversion_value next to all_conversions and all_conversion_value for every measured action, each with previous period figures.
googleads.accounts get_googleads_accounts Shows whether Google Ads is connected and which account_id is active, plus the accounts list of every Google Ads account the connected Google user can read. Includes client accounts under a manager account with account_id and name alongside currency and login_account_id.
googleads.account_set REST only (write) Activates one readable account_id from googleads.accounts (digits only or with dashes) for the site, returning the chosen account_id and name with its currency. Available to every role on the site, including guests.
googleads.disconnect REST only (write) Removes the Google login and selected Google Ads account from the site and returns {"connected": false}. Any user with access to the site can call it.

Reading Google Ads campaigns with curl or the MCP

Send a POST request with a JSON body and your API key in the Authorization: Bearer header. You can also send a GET request with the same arguments in the query string. Every response returns data and meta.

curl -X POST https://app.marketingtracer.com/rest/v1/googleads.campaigns \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"site_id": "YOUR_SITE_ID", "days": 28, "limit": 2}'
{
  "data": [
    {
      "campaign_id": "1100000001",
      "campaign": "Search | Brand",
      "status": "enabled",
      "channel_type": "search",
      "daily_budget": 40,
      "search_impression_share_pct": 87.3,
      "search_lost_budget_pct": 0,
      "search_lost_rank_pct": 12.7,
      "clicks": 696,
      "impressions": 26360,
      "ctr_pct": 2.64,
      "cost": 812.63,
      "average_cpc": 1.17,
      "conversions": 0,
      "conversion_rate_pct": 0,
      "cost_per_conversion": null,
      "conversion_value": 0,
      "roas": 0,
      "absolute_top_impression_pct": 9.8,
      "share_pct": 81.6,
      "previous": {
        "clicks": 646,
        "impressions": 20416,
        "ctr_pct": 3.16,
        "cost": 682.89,
        "average_cpc": 1.06,
        "conversions": 6,
        "conversion_rate_pct": 0.93,
        "cost_per_conversion": 113.81,
        "conversion_value": 0,
        "roas": 0,
        "absolute_top_impression_pct": 12.8
      }
    },
    {
      "campaign_id": "1100000002",
      "campaign": "Search | Running shoes",
      "status": "enabled",
      "channel_type": "search",
      "daily_budget": 25,
      "search_impression_share_pct": 41.2,
      "search_lost_budget_pct": 33.5,
      "search_lost_rank_pct": 25.3,
      "clicks": 48,
      "impressions": 117,
      "ctr_pct": 41.03,
      "cost": 27.41,
      "average_cpc": 0.57,
      "conversions": 2,
      "conversion_rate_pct": 4.17,
      "cost_per_conversion": 13.71,
      "conversion_value": 0,
      "roas": 0,
      "absolute_top_impression_pct": 95,
      "share_pct": 5.6,
      "previous": { … }
    }
  ],
  "meta": {
    "site_id": "YOUR_SITE_ID",
    "next_cursor": "2",
    "total": 8,
    "period": {
      "from": "2026-10-17",
      "to": "2026-11-13",
      "compare_from": "2026-09-19",
      "compare_to": "2026-10-16"
    },
    "currency": "USD"
  }
}

Connecting the MCP server

To query Google Ads from your AI assistant, connect the MarketingTracer MCP server in one of two ways:

  • Sign in with OAuth: Add the server URL in Claude.ai or Claude Desktop under Settings, Connectors, Add custom connector. In ChatGPT developer mode, add a custom connector with OAuth selected and leave the client ID and secret empty. For Claude Code, add the server and run /mcp. A login window opens on the dashboard domain where you sign in and click Allow.
  • Bearer API key: Create a key on the MCP page in the app (mtk_… for your personal login or mtw_… for a white label domain). Pass it in Claude Code, Cursor or your MCP config file:
claude mcp add --transport http marketingtracer https://app.marketingtracer.com/rest/mcp/server \
  --header "Authorization: Bearer YOUR_API_KEY"
Client reports

Put paid search next to organic in your monthly report

On the first of the month your report script calls googleads.summary and googleads.campaigns for the same site_id and date range as Search Console and GA4. Totals and ratios like CTR, average CPC and ROAS are calculated over the full period so your report matches the Google Ads interface.

Every campaign row includes its previous period numbers and the share of Search impressions lost to budget or ad rank, with the account currency in meta.currency. When a client calls on Monday to ask why conversions dipped, you can see right away whether a campaign hit its daily budget cap or slipped in ad rank.

Account spend (28d, USD)981.43 vs 884.58 (+10.9%)
Clicks · CTR853 +3.1% · 3.05%
Search | Brand ($40/d)87.3% share 12.7% lost rank
Search | Running shoes ($25/d)33.5% lost budget 25.3% lost rank

Which search terms are we paying for in Google Ads where we already rank in the top 3 in Search Console, and which converting paid queries have no organic page in the top 20?

get_googleads_search_terms · 28 days
get_googleads_keywords get_search_console get_scan_pages
MCP for specialists

Cross-check paid search terms against organic rankings in your AI

Before a client meeting, ask Claude or ChatGPT to combine get_googleads_search_terms and get_googleads_keywords with get_search_console over the last 28 days. Your assistant spots the queries where the client pays for clicks while already ranking first organically. It also flags converting paid search terms where the site has no organic page in the top 20 yet.

Each keyword in googleads.keywords comes with Google's quality_score from 1 to 10. When a low score points to a weak landing page, you can inspect that URL right away with the SEO audit tools.

Agency onboarding

Pick client accounts under a manager account with zero risk to live ads

Anyone with access to the site in MarketingTracer (even a client on a guest login) can sign in with Google once in the app to connect Google Ads. Your settings page then calls googleads.accounts to list every Google Ads account that login can read, down to client accounts under a manager account. A single call to googleads.account_set activates the chosen account for the site.

The Google Ads integration has read-only access to reporting data. An agency script or AI assistant cannot pause a campaign or touch a client's budgets and bids.

Manager accountlogin_account_id: 3300000001
Example shop (3300000002)USD Active
Example shop (BE) (3300000003)USD Readable
Write access in Google AdsReporting only

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.

googleads.summary

POST /rest/v1/googleads.summary · MCP tool get_googleads_summary

Returns the Google Ads totals of the chosen account of one site for the period against the previous period: clicks, impressions, CTR, cost, cost per click, conversions, conversion rate, cost per conversion, conversion value, ROAS and absolute top impression share, each as value, previous, change and change in percent; plus per day the same metrics for both periods. 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 Google Ads is not connected for the site (or the connection expired), 409 no_account when no 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/googleads.summary \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"site_id":"YOUR_SITE_ID","days":28}'

Example response · A real answer of 14 November 2026 for a small site, anonymised (names and ids made up); lists cut to two items.

{
  "data": {
    "compare": "previous_period",
    "clicks": {"value": 853, "previous": 827, "change": 26, "change_pct": 3.1},
    "impressions": {"value": 27970, "previous": 22811, "change": 5159, "change_pct": 22.6},
    "ctr_pct": {"value": 3.05, "previous": 3.63, "change": -0.58, "change_pct": -16},
    "cost": {"value": 981.43, "previous": 884.58, "change": 96.85, "change_pct": 10.9},
    "average_cpc": {"value": 1.15, "previous": 1.07, "change": 0.08, "change_pct": 7.5},
    "conversions": {"value": 4, "previous": 8, "change": -4, "change_pct": -50},
    "conversion_rate_pct": {"value": 0.47, "previous": 0.97, "change": -0.5, "change_pct": -51.5},
    "cost_per_conversion": {"value": 245.36, "previous": 110.57, "change": 134.79, "change_pct": 121.9},
    "conversion_value": {"value": 0, "previous": 0, "change": 0, "change_pct": null},
    "roas": {"value": 0, "previous": 0, "change": 0, "change_pct": null},
    "absolute_top_impression_pct": {"value": 10.6, "previous": 13.3, "change": -2.7, "change_pct": -20.3},
    "daily": [
      {
        "date": "2026-10-17",
        "clicks": 25,
        "impressions": 983,
        "ctr_pct": 2.54,
        "cost": 34.46,
        "average_cpc": 1.38,
        "conversions": 0,
        "conversion_rate_pct": 0,
        "cost_per_conversion": null,
        "conversion_value": 0,
        "roas": 0,
        "absolute_top_impression_pct": 9.8,
        "previous_date": "2026-09-19",
        "previous": {
          "clicks": 19,
          "impressions": 494,
          "ctr_pct": 3.85,
          "cost": 21.12,
          "average_cpc": 1.11,
          "conversions": 0,
          "conversion_rate_pct": 0,
          "cost_per_conversion": null,
          "conversion_value": 0,
          "roas": 0,
          "absolute_top_impression_pct": 12.6
        }
      },
      {
        "date": "2026-10-18",
        "clicks": 34,
        "impressions": 833,
        "ctr_pct": 4.08,
        "cost": 71.83,
        "average_cpc": 2.11,
        "conversions": 0,
        "conversion_rate_pct": 0,
        "cost_per_conversion": null,
        "conversion_value": 0,
        "roas": 0,
        "absolute_top_impression_pct": 13.4,
        "previous_date": "2026-09-20",
        "previous": {
          "clicks": 30,
          "impressions": 698,
          "ctr_pct": 4.3,
          "cost": 27.12,
          "average_cpc": 0.9,
          "conversions": 0,
          "conversion_rate_pct": 0,
          "cost_per_conversion": null,
          "conversion_value": 0,
          "roas": 0,
          "absolute_top_impression_pct": 11.6
        }
      }
    ]
  },
  "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": "USD"
  }
}

Response fields · in data:

FieldTypeWhat it is
comparestringprevious_period or previous_year: what the previous figures are.
clicksobjectClicks 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.
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.
ctr_pctobjectCTR, 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.
costobjectCost 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.
average_cpcobjectCost per 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.
conversionsobjectConversions in the period, against the previous period.
conversions.valuenumber or nullThis period; null when it does not apply.
conversions.previousnumber or nullThe previous period; null when it does not apply.
conversions.changenumber or nullvalue minus previous.
conversions.change_pctnumber or nullThe change in percent of previous; null when previous is 0 or null.
conversion_rate_pctobjectConversion rate, 0-100, in the period, against the previous period.
conversion_rate_pct.valuenumber or nullThis period; null when it does not apply.
conversion_rate_pct.previousnumber or nullThe previous period; null when it does not apply.
conversion_rate_pct.changenumber or nullvalue minus previous, in percentage points.
conversion_rate_pct.change_pctnumber or nullThe change in percent of previous; null when previous is 0 or null.
cost_per_conversionobjectCost per conversion in the period, against the previous period.
cost_per_conversion.valuenumber or nullThis period; null when it does not apply.
cost_per_conversion.previousnumber or nullThe previous period; null when it does not apply.
cost_per_conversion.changenumber or nullvalue minus previous.
cost_per_conversion.change_pctnumber or nullThe change in percent of previous; null when previous is 0 or null.
conversion_valueobjectConversion value in the period, against the previous period.
conversion_value.valuenumber or nullThis period; null when it does not apply.
conversion_value.previousnumber or nullThe previous period; null when it does not apply.
conversion_value.changenumber or nullvalue minus previous.
conversion_value.change_pctnumber or nullThe change in percent of previous; null when previous is 0 or null.
roasobjectROAS (conversion 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.
absolute_top_impression_pctobjectAbsolute top impression share, 0-100, in the period, against the previous period.
absolute_top_impression_pct.valuenumber or nullThis period; null when it does not apply.
absolute_top_impression_pct.previousnumber or nullThe previous period; null when it does not apply.
absolute_top_impression_pct.changenumber or nullvalue minus previous, in percentage points.
absolute_top_impression_pct.change_pctnumber or nullThe change in percent of previous; null when previous is 0 or null.
dailyarrayPer day of the period, oldest first, with all metrics, next to the matching day of the previous period.
daily[].datestringThe day, YYYY-MM-DD.
daily[].clicksintegerClicks.
daily[].impressionsintegerImpressions.
daily[].ctr_pctnumber or nullClicks as a share of impressions, 0-100; null without impressions.
daily[].costnumberCost, in the currency of the Google Ads account (meta.currency).
daily[].average_cpcnumber or nullCost per click; null without clicks.
daily[].conversionsnumberConversions (the conversion actions counted in Conversions in Google Ads; can be fractional with data-driven attribution).
daily[].conversion_rate_pctnumber or nullConversions as a share of interactions (clicks, calls, video views), 0-100; null without interactions.
daily[].cost_per_conversionnumber or nullCost per conversion; null without conversions.
daily[].conversion_valuenumberValue of the conversions, in the account currency.
daily[].roasnumber or nullReturn on ad spend: conversion_value divided by cost (3.5 = 3.5 times the cost back); null without cost.
daily[].absolute_top_impression_pctnumber or nullShare of the search impressions shown as the very first ad above the results, 0-100; null without impressions.
daily[].previous_datestringThe matching day of the previous period, YYYY-MM-DD.
daily[].previousobjectThe same figures on previous_date.
daily[].previous.clicksintegerClicks.
daily[].previous.impressionsintegerImpressions.
daily[].previous.ctr_pctnumber or nullClicks as a share of impressions, 0-100; null without impressions.
daily[].previous.costnumberCost, in the currency of the Google Ads account (meta.currency).
daily[].previous.average_cpcnumber or nullCost per click; null without clicks.
daily[].previous.conversionsnumberConversions (the conversion actions counted in Conversions in Google Ads; can be fractional with data-driven attribution).
daily[].previous.conversion_rate_pctnumber or nullConversions as a share of interactions (clicks, calls, video views), 0-100; null without interactions.
daily[].previous.cost_per_conversionnumber or nullCost per conversion; null without conversions.
daily[].previous.conversion_valuenumberValue of the conversions, in the account currency.
daily[].previous.roasnumber or nullReturn on ad spend: conversion_value divided by cost (3.5 = 3.5 times the cost back); null without cost.
daily[].previous.absolute_top_impression_pctnumber or nullShare of the search impressions shown as the very first ad above the results, 0-100; null without impressions.

googleads.campaigns

POST /rest/v1/googleads.campaigns · MCP tool get_googleads_campaigns

Returns the campaigns of the chosen Google Ads account of one site that had impressions in the period, most clicks first: all metrics, the share of all clicks 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 Google Ads is not connected for the site (or the connection expired), 409 no_account when no 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/googleads.campaigns \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"site_id":"YOUR_SITE_ID","days":28,"limit":2}'

Example response · A real answer of 14 November 2026 for a small site, anonymised (names and ids made up); lists cut to two items.

{
  "data": [
    {
      "campaign_id": "1100000001",
      "campaign": "Search | Brand",
      "status": "enabled",
      "channel_type": "search",
      "daily_budget": 40,
      "search_impression_share_pct": 87.3,
      "search_lost_budget_pct": 0,
      "search_lost_rank_pct": 12.7,
      "clicks": 696,
      "impressions": 26360,
      "ctr_pct": 2.64,
      "cost": 812.63,
      "average_cpc": 1.17,
      "conversions": 0,
      "conversion_rate_pct": 0,
      "cost_per_conversion": null,
      "conversion_value": 0,
      "roas": 0,
      "absolute_top_impression_pct": 9.8,
      "share_pct": 81.6,
      "previous": {
        "clicks": 646,
        "impressions": 20416,
        "ctr_pct": 3.16,
        "cost": 682.89,
        "average_cpc": 1.06,
        "conversions": 6,
        "conversion_rate_pct": 0.93,
        "cost_per_conversion": 113.81,
        "conversion_value": 0,
        "roas": 0,
        "absolute_top_impression_pct": 12.8
      }
    },
    {
      "campaign_id": "1100000002",
      "campaign": "Search | Running shoes",
      "status": "enabled",
      "channel_type": "search",
      "daily_budget": 25,
      "search_impression_share_pct": 41.2,
      "search_lost_budget_pct": 33.5,
      "search_lost_rank_pct": 25.3,
      "clicks": 48,
      "impressions": 117,
      "ctr_pct": 41.03,
      "cost": 27.41,
      "average_cpc": 0.57,
      "conversions": 2,
      "conversion_rate_pct": 4.17,
      "cost_per_conversion": 13.71,
      "conversion_value": 0,
      "roas": 0,
      "absolute_top_impression_pct": 95,
      "share_pct": 5.6,
      "previous": {
        "clicks": 67,
        "impressions": 152,
        "ctr_pct": 44.08,
        "cost": 45.36,
        "average_cpc": 0.68,
        "conversions": 1,
        "conversion_rate_pct": 1.49,
        "cost_per_conversion": 45.36,
        "conversion_value": 0,
        "roas": 0,
        "absolute_top_impression_pct": 93.3
      }
    }
  ],
  "meta": {
    "site_id": "YOUR_SITE_ID",
    "next_cursor": "2",
    "total": 8,
    "period": {
      "from": "2026-10-17",
      "to": "2026-11-13",
      "compare_from": "2026-09-19",
      "compare_to": "2026-10-16"
    },
    "currency": "USD"
  }
}

Response fields · data is a list; each item has:

FieldTypeWhat it is
campaign_idstringThe campaign id in Google Ads.
campaignstringThe campaign name.
statusstring or nullenabled, paused or removed (now, not in the period).
channel_typestring or nullsearch, display, shopping, video, performance_max, …
daily_budgetnumber or nullThe daily budget now (not in the period), in the account currency; for a shared budget the shared amount; null when Google gives none.
search_impression_share_pctnumber or nullImpressions on Google Search as a share of the impressions the campaign could have had, 0-100 (Google gives under 10% as 9.99); null for campaigns that are not on Search or Shopping.
search_lost_budget_pctnumber or nullThe share of possible Search impressions missed because the budget ran out, 0-100; null like search_impression_share_pct.
search_lost_rank_pctnumber or nullThe share of possible Search impressions missed because of ad rank (bid and quality), 0-100; null like search_impression_share_pct.
clicksintegerClicks.
impressionsintegerImpressions.
ctr_pctnumber or nullClicks as a share of impressions, 0-100; null without impressions.
costnumberCost, in the currency of the Google Ads account (meta.currency).
average_cpcnumber or nullCost per click; null without clicks.
conversionsnumberConversions (the conversion actions counted in Conversions in Google Ads; can be fractional with data-driven attribution).
conversion_rate_pctnumber or nullConversions as a share of interactions (clicks, calls, video views), 0-100; null without interactions.
cost_per_conversionnumber or nullCost per conversion; null without conversions.
conversion_valuenumberValue of the conversions, in the account currency.
roasnumber or nullReturn on ad spend: conversion_value divided by cost (3.5 = 3.5 times the cost back); null without cost.
absolute_top_impression_pctnumber or nullShare of the search impressions shown as the very first ad above the results, 0-100; null without impressions.
share_pctnumber or nullShare of the clicks of the whole list, 0-100; null when the list has no clicks.
previousobject or nullThe same figures in the previous period; null when it had no impressions then.
previous.clicksintegerClicks.
previous.impressionsintegerImpressions.
previous.ctr_pctnumber or nullClicks as a share of impressions, 0-100; null without impressions.
previous.costnumberCost, in the currency of the Google Ads account (meta.currency).
previous.average_cpcnumber or nullCost per click; null without clicks.
previous.conversionsnumberConversions (the conversion actions counted in Conversions in Google Ads; can be fractional with data-driven attribution).
previous.conversion_rate_pctnumber or nullConversions as a share of interactions (clicks, calls, video views), 0-100; null without interactions.
previous.cost_per_conversionnumber or nullCost per conversion; null without conversions.
previous.conversion_valuenumberValue of the conversions, in the account currency.
previous.roasnumber or nullReturn on ad spend: conversion_value divided by cost (3.5 = 3.5 times the cost back); null without cost.
previous.absolute_top_impression_pctnumber or nullShare of the search impressions shown as the very first ad above the results, 0-100; null without impressions.

googleads.ad_groups

POST /rest/v1/googleads.ad_groups · MCP tool get_googleads_ad_groups

Returns the ad groups of the chosen Google Ads account of one site that had impressions in the period, most clicks first, with their campaign: all metrics, the share of all clicks and the same figures in the previous period. Performance Max has no ad groups. 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 Google Ads is not connected for the site (or the connection expired), 409 no_account when no 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/googleads.ad_groups \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"site_id":"YOUR_SITE_ID","days":28,"limit":2}'

Example response · A real answer of 14 November 2026 for a small site, anonymised (names and ids made up); lists cut to two items.

{
  "data": [
    {
      "ad_group_id": "2200000001",
      "ad_group": "Trail shoes",
      "status": "enabled",
      "campaign_id": "1100000001",
      "campaign": "Search | Brand",
      "clicks": 414,
      "impressions": 14855,
      "ctr_pct": 2.79,
      "cost": 510.01,
      "average_cpc": 1.23,
      "conversions": 0,
      "conversion_rate_pct": 0,
      "cost_per_conversion": null,
      "conversion_value": 0,
      "roas": 0,
      "absolute_top_impression_pct": 9.5,
      "share_pct": 48.5,
      "previous": {
        "clicks": 378,
        "impressions": 11996,
        "ctr_pct": 3.15,
        "cost": 412.79,
        "average_cpc": 1.09,
        "conversions": 6,
        "conversion_rate_pct": 1.59,
        "cost_per_conversion": 68.8,
        "conversion_value": 0,
        "roas": 0,
        "absolute_top_impression_pct": 12.3
      }
    },
    {
      "ad_group_id": "2200000002",
      "ad_group": "Brand",
      "status": "enabled",
      "campaign_id": "1100000002",
      "campaign": "Search | Running shoes",
      "clicks": 104,
      "impressions": 4199,
      "ctr_pct": 2.48,
      "cost": 121.96,
      "average_cpc": 1.17,
      "conversions": 0,
      "conversion_rate_pct": 0,
      "cost_per_conversion": null,
      "conversion_value": 0,
      "roas": 0,
      "absolute_top_impression_pct": 14.1,
      "share_pct": 12.2,
      "previous": {
        "clicks": 110,
        "impressions": 3672,
        "ctr_pct": 3,
        "cost": 118.38,
        "average_cpc": 1.08,
        "conversions": 0,
        "conversion_rate_pct": 0,
        "cost_per_conversion": null,
        "conversion_value": 0,
        "roas": 0,
        "absolute_top_impression_pct": 14.4
      }
    }
  ],
  "meta": {
    "site_id": "YOUR_SITE_ID",
    "next_cursor": "2",
    "total": 42,
    "period": {
      "from": "2026-10-17",
      "to": "2026-11-13",
      "compare_from": "2026-09-19",
      "compare_to": "2026-10-16"
    },
    "currency": "USD"
  }
}

Response fields · data is a list; each item has:

FieldTypeWhat it is
ad_group_idstringThe ad group id in Google Ads.
ad_groupstringThe ad group name.
statusstring or nullenabled, paused or removed (now, not in the period).
campaign_idstringThe campaign it is in.
campaignstringThe campaign name.
clicksintegerClicks.
impressionsintegerImpressions.
ctr_pctnumber or nullClicks as a share of impressions, 0-100; null without impressions.
costnumberCost, in the currency of the Google Ads account (meta.currency).
average_cpcnumber or nullCost per click; null without clicks.
conversionsnumberConversions (the conversion actions counted in Conversions in Google Ads; can be fractional with data-driven attribution).
conversion_rate_pctnumber or nullConversions as a share of interactions (clicks, calls, video views), 0-100; null without interactions.
cost_per_conversionnumber or nullCost per conversion; null without conversions.
conversion_valuenumberValue of the conversions, in the account currency.
roasnumber or nullReturn on ad spend: conversion_value divided by cost (3.5 = 3.5 times the cost back); null without cost.
absolute_top_impression_pctnumber or nullShare of the search impressions shown as the very first ad above the results, 0-100; null without impressions.
share_pctnumber or nullShare of the clicks of the whole list, 0-100; null when the list has no clicks.
previousobject or nullThe same figures in the previous period; null when it had no impressions then.
previous.clicksintegerClicks.
previous.impressionsintegerImpressions.
previous.ctr_pctnumber or nullClicks as a share of impressions, 0-100; null without impressions.
previous.costnumberCost, in the currency of the Google Ads account (meta.currency).
previous.average_cpcnumber or nullCost per click; null without clicks.
previous.conversionsnumberConversions (the conversion actions counted in Conversions in Google Ads; can be fractional with data-driven attribution).
previous.conversion_rate_pctnumber or nullConversions as a share of interactions (clicks, calls, video views), 0-100; null without interactions.
previous.cost_per_conversionnumber or nullCost per conversion; null without conversions.
previous.conversion_valuenumberValue of the conversions, in the account currency.
previous.roasnumber or nullReturn on ad spend: conversion_value divided by cost (3.5 = 3.5 times the cost back); null without cost.
previous.absolute_top_impression_pctnumber or nullShare of the search impressions shown as the very first ad above the results, 0-100; null without impressions.

googleads.search_terms

POST /rest/v1/googleads.search_terms · MCP tool get_googleads_search_terms

Returns the search terms people typed when an ad of the chosen Google Ads account of one site was shown in the period (the search terms report, summed over ad groups), most clicks first: all metrics, the share of all clicks and the same figures in the previous period. Google leaves out rare search terms for privacy, and gives at most the 5,000 with the most impressions per 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 Google Ads is not connected for the site (or the connection expired), 409 no_account when no 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/googleads.search_terms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"site_id":"YOUR_SITE_ID","days":28,"limit":2}'

Example response · A real answer of 14 November 2026 for a small site, anonymised (names and ids made up); lists cut to two items.

{
  "data": [
    {
      "search_term": "trail running shoes",
      "clicks": 22,
      "impressions": 66,
      "ctr_pct": 33.33,
      "cost": 4.35,
      "average_cpc": 0.2,
      "conversions": 0,
      "conversion_rate_pct": 0,
      "cost_per_conversion": null,
      "conversion_value": 0,
      "roas": 0,
      "absolute_top_impression_pct": 89.2,
      "share_pct": 4.1,
      "previous": {
        "clicks": 24,
        "impressions": 59,
        "ctr_pct": 40.68,
        "cost": 2.13,
        "average_cpc": 0.09,
        "conversions": 0,
        "conversion_rate_pct": 0,
        "cost_per_conversion": null,
        "conversion_value": 0,
        "roas": 0,
        "absolute_top_impression_pct": 87.7
      }
    },
    {
      "search_term": "running shoes sale",
      "clicks": 12,
      "impressions": 124,
      "ctr_pct": 9.68,
      "cost": 8.83,
      "average_cpc": 0.74,
      "conversions": 0,
      "conversion_rate_pct": 0,
      "cost_per_conversion": null,
      "conversion_value": 0,
      "roas": 0,
      "absolute_top_impression_pct": 21,
      "share_pct": 2.2,
      "previous": {
        "clicks": 1,
        "impressions": 83,
        "ctr_pct": 1.2,
        "cost": 0.34,
        "average_cpc": 0.34,
        "conversions": 0,
        "conversion_rate_pct": 0,
        "cost_per_conversion": null,
        "conversion_value": 0,
        "roas": 0,
        "absolute_top_impression_pct": 10.8
      }
    }
  ],
  "meta": {
    "site_id": "YOUR_SITE_ID",
    "next_cursor": "2",
    "total": 4824,
    "period": {
      "from": "2026-10-17",
      "to": "2026-11-13",
      "compare_from": "2026-09-19",
      "compare_to": "2026-10-16"
    },
    "currency": "USD"
  }
}

Response fields · data is a list; each item has:

FieldTypeWhat it is
search_termstringThe search term as typed.
clicksintegerClicks.
impressionsintegerImpressions.
ctr_pctnumber or nullClicks as a share of impressions, 0-100; null without impressions.
costnumberCost, in the currency of the Google Ads account (meta.currency).
average_cpcnumber or nullCost per click; null without clicks.
conversionsnumberConversions (the conversion actions counted in Conversions in Google Ads; can be fractional with data-driven attribution).
conversion_rate_pctnumber or nullConversions as a share of interactions (clicks, calls, video views), 0-100; null without interactions.
cost_per_conversionnumber or nullCost per conversion; null without conversions.
conversion_valuenumberValue of the conversions, in the account currency.
roasnumber or nullReturn on ad spend: conversion_value divided by cost (3.5 = 3.5 times the cost back); null without cost.
absolute_top_impression_pctnumber or nullShare of the search impressions shown as the very first ad above the results, 0-100; null without impressions.
share_pctnumber or nullShare of the clicks of the whole list, 0-100; null when the list has no clicks.
previousobject or nullThe same figures in the previous period; null when it had no impressions then.
previous.clicksintegerClicks.
previous.impressionsintegerImpressions.
previous.ctr_pctnumber or nullClicks as a share of impressions, 0-100; null without impressions.
previous.costnumberCost, in the currency of the Google Ads account (meta.currency).
previous.average_cpcnumber or nullCost per click; null without clicks.
previous.conversionsnumberConversions (the conversion actions counted in Conversions in Google Ads; can be fractional with data-driven attribution).
previous.conversion_rate_pctnumber or nullConversions as a share of interactions (clicks, calls, video views), 0-100; null without interactions.
previous.cost_per_conversionnumber or nullCost per conversion; null without conversions.
previous.conversion_valuenumberValue of the conversions, in the account currency.
previous.roasnumber or nullReturn on ad spend: conversion_value divided by cost (3.5 = 3.5 times the cost back); null without cost.
previous.absolute_top_impression_pctnumber or nullShare of the search impressions shown as the very first ad above the results, 0-100; null without impressions.

googleads.keywords

POST /rest/v1/googleads.keywords · MCP tool get_googleads_keywords

Returns the keywords the chosen Google Ads account of one site bids on that had impressions in the period, most clicks first, with match type, quality score, ad group and campaign: all metrics, the share of all clicks and the same figures in the previous period. These are the keywords you chose; googleads.search_terms gives what people actually typed. At most the 5,000 with the most impressions per 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 Google Ads is not connected for the site (or the connection expired), 409 no_account when no 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/googleads.keywords \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"site_id":"YOUR_SITE_ID","days":28,"limit":3}'

Example response ·

{
  "data": [
    {
      "keyword": "yourwebshop",
      "match_type": "exact",
      "status": "enabled",
      "quality_score": 10,
      "ad_group_id": "13405695032",
      "ad_group": "Brand name",
      "campaign_id": "11459965844",
      "campaign": "Brand",
      "clicks": 1385,
      "impressions": 4232,
      "ctr_pct": 32.73,
      "cost": 390.94,
      "average_cpc": 0.28,
      "conversions": 144.65,
      "conversion_rate_pct": 10.44,
      "cost_per_conversion": 2.7,
      "conversion_value": 11311.91,
      "roas": 28.94,
      "absolute_top_impression_pct": 78,
      "share_pct": 19.3,
      "previous": {
        "clicks": 1253,
        "impressions": 3780,
        "ctr_pct": 33.15,
        "cost": 348.64,
        "average_cpc": 0.28,
        "conversions": 138.12,
        "conversion_rate_pct": 11.02,
        "cost_per_conversion": 2.52,
        "conversion_value": 10800.68,
        "roas": 30.98,
        "absolute_top_impression_pct": 78
      }
    },
    {
      "keyword": "running shoes",
      "match_type": "exact",
      "status": "enabled",
      "quality_score": 7,
      "ad_group_id": "10370889417",
      "ad_group": "Women",
      "campaign_id": "13552401607",
      "campaign": "Running shoes",
      "clicks": 1193,
      "impressions": 16702,
      "ctr_pct": 7.14,
      "cost": 750.49,
      "average_cpc": 0.63,
      "conversions": 41.67,
      "conversion_rate_pct": 3.49,
      "cost_per_conversion": 18.01,
      "conversion_value": 4179.92,
      "roas": 5.57,
      "absolute_top_impression_pct": 31,
      "share_pct": 16.6,
      "previous": {
        "clicks": 1014,
        "impressions": 14809,
        "ctr_pct": 6.85,
        "cost": 621.83,
        "average_cpc": 0.61,
        "conversions": 29.82,
        "conversion_rate_pct": 2.94,
        "cost_per_conversion": 20.85,
        "conversion_value": 2990.93,
        "roas": 4.81,
        "absolute_top_impression_pct": 31
      }
    },
    {
      "keyword": "trail shoes",
      "match_type": "exact",
      "status": "enabled",
      "quality_score": 7,
      "ad_group_id": "10891665084",
      "ad_group": "Trail shoes",
      "campaign_id": "12612000565",
      "campaign": "Trail shoes",
      "clicks": 744,
      "impressions": 14660,
      "ctr_pct": 5.08,
      "cost": 414.46,
      "average_cpc": 0.56,
      "conversions": 24.98,
      "conversion_rate_pct": 3.36,
      "cost_per_conversion": 16.59,
      "conversion_value": 2717.9,
      "roas": 6.56,
      "absolute_top_impression_pct": 36,
      "share_pct": 10.4,
      "previous": {
        "clicks": 703,
        "impressions": 13463,
        "ctr_pct": 5.22,
        "cost": 397.54,
        "average_cpc": 0.57,
        "conversions": 23.73,
        "conversion_rate_pct": 3.38,
        "cost_per_conversion": 16.75,
        "conversion_value": 2581.69,
        "roas": 6.49,
        "absolute_top_impression_pct": 36
      }
    }
  ],
  "meta": {
    "site_id": "YOUR_SITE_ID",
    "next_cursor": "3",
    "total": 14,
    "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
keywordstringThe keyword as set in Google Ads.
match_typestring or nullexact, phrase or broad.
statusstring or nullenabled, paused or removed (now, not in the period).
quality_scoreinteger or nullGoogle's quality score now, 1-10; null when Google has too little data.
ad_group_idstringThe ad group it is in.
ad_groupstringThe ad group name.
campaign_idstringThe campaign it is in.
campaignstringThe campaign name.
clicksintegerClicks.
impressionsintegerImpressions.
ctr_pctnumber or nullClicks as a share of impressions, 0-100; null without impressions.
costnumberCost, in the currency of the Google Ads account (meta.currency).
average_cpcnumber or nullCost per click; null without clicks.
conversionsnumberConversions (the conversion actions counted in Conversions in Google Ads; can be fractional with data-driven attribution).
conversion_rate_pctnumber or nullConversions as a share of interactions (clicks, calls, video views), 0-100; null without interactions.
cost_per_conversionnumber or nullCost per conversion; null without conversions.
conversion_valuenumberValue of the conversions, in the account currency.
roasnumber or nullReturn on ad spend: conversion_value divided by cost (3.5 = 3.5 times the cost back); null without cost.
absolute_top_impression_pctnumber or nullShare of the search impressions shown as the very first ad above the results, 0-100; null without impressions.
share_pctnumber or nullShare of the clicks of the whole list, 0-100; null when the list has no clicks.
previousobject or nullThe same figures in the previous period; null when it had no impressions then.
previous.clicksintegerClicks.
previous.impressionsintegerImpressions.
previous.ctr_pctnumber or nullClicks as a share of impressions, 0-100; null without impressions.
previous.costnumberCost, in the currency of the Google Ads account (meta.currency).
previous.average_cpcnumber or nullCost per click; null without clicks.
previous.conversionsnumberConversions (the conversion actions counted in Conversions in Google Ads; can be fractional with data-driven attribution).
previous.conversion_rate_pctnumber or nullConversions as a share of interactions (clicks, calls, video views), 0-100; null without interactions.
previous.cost_per_conversionnumber or nullCost per conversion; null without conversions.
previous.conversion_valuenumberValue of the conversions, in the account currency.
previous.roasnumber or nullReturn on ad spend: conversion_value divided by cost (3.5 = 3.5 times the cost back); null without cost.
previous.absolute_top_impression_pctnumber or nullShare of the search impressions shown as the very first ad above the results, 0-100; null without impressions.

googleads.devices

POST /rest/v1/googleads.devices · MCP tool get_googleads_devices

Returns the Google Ads figures of the chosen account of one site per device (mobile, desktop, tablet, connected_tv, other) in the period, most clicks first: all metrics, the share of all clicks 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 Google Ads is not connected for the site (or the connection expired), 409 no_account when no 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/googleads.devices \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"site_id":"YOUR_SITE_ID","days":28,"limit":3}'

Example response ·

{
  "data": [
    {
      "device": "mobile",
      "clicks": 7286,
      "impressions": 333405,
      "ctr_pct": 2.19,
      "cost": 3465.65,
      "average_cpc": 0.48,
      "conversions": 199.68,
      "conversion_rate_pct": 2.74,
      "cost_per_conversion": 17.36,
      "conversion_value": 17693.27,
      "roas": 5.11,
      "absolute_top_impression_pct": 0,
      "share_pct": 66.1,
      "previous": {
        "clicks": 6807,
        "impressions": 371349,
        "ctr_pct": 1.83,
        "cost": 3091.25,
        "average_cpc": 0.45,
        "conversions": 180.87,
        "conversion_rate_pct": 2.66,
        "cost_per_conversion": 17.09,
        "conversion_value": 15820.01,
        "roas": 5.12,
        "absolute_top_impression_pct": 0
      }
    },
    {
      "device": "desktop",
      "clicks": 2956,
      "impressions": 164056,
      "ctr_pct": 1.8,
      "cost": 1406.11,
      "average_cpc": 0.48,
      "conversions": 178.09,
      "conversion_rate_pct": 6.02,
      "cost_per_conversion": 7.9,
      "conversion_value": 15780.48,
      "roas": 11.22,
      "absolute_top_impression_pct": 0,
      "share_pct": 26.8,
      "previous": {
        "clicks": 2762,
        "impressions": 182727,
        "ctr_pct": 1.51,
        "cost": 1254.21,
        "average_cpc": 0.45,
        "conversions": 161.32,
        "conversion_rate_pct": 5.84,
        "cost_per_conversion": 7.77,
        "conversion_value": 14109.74,
        "roas": 11.25,
        "absolute_top_impression_pct": 0
      }
    },
    {
      "device": "tablet",
      "clicks": 773,
      "impressions": 31753,
      "ctr_pct": 2.43,
      "cost": 367.85,
      "average_cpc": 0.48,
      "conversions": 25.83,
      "conversion_rate_pct": 3.34,
      "cost_per_conversion": 14.24,
      "conversion_value": 2289.1,
      "roas": 6.22,
      "absolute_top_impression_pct": 0,
      "share_pct": 7,
      "previous": {
        "clicks": 722,
        "impressions": 35367,
        "ctr_pct": 2.04,
        "cost": 328.11,
        "average_cpc": 0.45,
        "conversions": 23.4,
        "conversion_rate_pct": 3.24,
        "cost_per_conversion": 14.02,
        "conversion_value": 2046.74,
        "roas": 6.24,
        "absolute_top_impression_pct": 0
      }
    }
  ],
  "meta": {
    "site_id": "YOUR_SITE_ID",
    "next_cursor": null,
    "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
devicestringmobile, desktop, tablet, connected_tv or other.
clicksintegerClicks.
impressionsintegerImpressions.
ctr_pctnumber or nullClicks as a share of impressions, 0-100; null without impressions.
costnumberCost, in the currency of the Google Ads account (meta.currency).
average_cpcnumber or nullCost per click; null without clicks.
conversionsnumberConversions (the conversion actions counted in Conversions in Google Ads; can be fractional with data-driven attribution).
conversion_rate_pctnumber or nullConversions as a share of interactions (clicks, calls, video views), 0-100; null without interactions.
cost_per_conversionnumber or nullCost per conversion; null without conversions.
conversion_valuenumberValue of the conversions, in the account currency.
roasnumber or nullReturn on ad spend: conversion_value divided by cost (3.5 = 3.5 times the cost back); null without cost.
absolute_top_impression_pctnumber or nullShare of the search impressions shown as the very first ad above the results, 0-100; null without impressions.
share_pctnumber or nullShare of the clicks of the whole list, 0-100; null when the list has no clicks.
previousobject or nullThe same figures in the previous period; null when it had no impressions then.
previous.clicksintegerClicks.
previous.impressionsintegerImpressions.
previous.ctr_pctnumber or nullClicks as a share of impressions, 0-100; null without impressions.
previous.costnumberCost, in the currency of the Google Ads account (meta.currency).
previous.average_cpcnumber or nullCost per click; null without clicks.
previous.conversionsnumberConversions (the conversion actions counted in Conversions in Google Ads; can be fractional with data-driven attribution).
previous.conversion_rate_pctnumber or nullConversions as a share of interactions (clicks, calls, video views), 0-100; null without interactions.
previous.cost_per_conversionnumber or nullCost per conversion; null without conversions.
previous.conversion_valuenumberValue of the conversions, in the account currency.
previous.roasnumber or nullReturn on ad spend: conversion_value divided by cost (3.5 = 3.5 times the cost back); null without cost.
previous.absolute_top_impression_pctnumber or nullShare of the search impressions shown as the very first ad above the results, 0-100; null without impressions.

googleads.conversions

POST /rest/v1/googleads.conversions · MCP tool get_googleads_conversions

Returns the conversions of the chosen Google Ads account of one site per conversion action (purchase, lead form, call, …) in the period, most first, with the same figures in the previous period. conversions counts only the actions set to count in Conversions in Google Ads; all_conversions counts every action. 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 Google Ads is not connected for the site (or the connection expired), 409 no_account when no 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/googleads.conversions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"site_id":"YOUR_SITE_ID","days":28,"limit":2}'

Example response · A real answer of 14 November 2026 for a small site, anonymised (names and ids made up); lists cut to two items.

{
  "data": [
    {
      "conversion_action": "Purchase",
      "conversions": 2,
      "conversion_value": 0,
      "all_conversions": 2,
      "all_conversion_value": 0,
      "previous": null
    },
    {
      "conversion_action": "Newsletter sign-up",
      "conversions": 1,
      "conversion_value": 0,
      "all_conversions": 1,
      "all_conversion_value": 0,
      "previous": {
        "conversions": 1,
        "conversion_value": 0,
        "all_conversions": 1,
        "all_conversion_value": 0
      }
    }
  ],
  "meta": {
    "site_id": "YOUR_SITE_ID",
    "next_cursor": null,
    "total": 3,
    "period": {
      "from": "2026-10-17",
      "to": "2026-11-13",
      "compare_from": "2026-09-19",
      "compare_to": "2026-10-16"
    },
    "currency": "USD"
  }
}

Response fields · data is a list; each item has:

FieldTypeWhat it is
conversion_actionstringThe name of the conversion action in Google Ads.
conversionsnumberConversions (only when the action counts in Conversions).
conversion_valuenumberTheir value, in the account currency.
all_conversionsnumberAll conversions of this action.
all_conversion_valuenumberTheir value.
previousobject or nullThe same figures in the previous period; null when the action had no conversions then.
previous.conversionsnumberConversions.
previous.conversion_valuenumberConversion value.
previous.all_conversionsnumberAll conversions.
previous.all_conversion_valuenumberAll conversion value.

googleads.accounts

POST /rest/v1/googleads.accounts · MCP tool get_googleads_accounts

Returns the Google Ads connection of the site: whether a Google user is connected, the chosen account, and every Google Ads account that user can read, also under a manager account (to choose one with googleads.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/googleads.accounts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"site_id":"YOUR_SITE_ID"}'

Example response · Illustrative: a connected Google user with two accounts under one manager account (ids and names made up).

{
  "data": {
    "connected": true,
    "account_id": "3300000002",
    "accounts": [
      {
        "account_id": "3300000002",
        "name": "Example shop",
        "currency": "USD",
        "login_account_id": "3300000001"
      },
      {
        "account_id": "3300000003",
        "name": "Example shop (BE)",
        "currency": "USD",
        "login_account_id": "3300000001"
      }
    ]
  },
  "meta": {"site_id": "YOUR_SITE_ID"}
}

Response fields · in data:

FieldTypeWhat it is
connectedbooleanWhether a Google user with Google Ads access is connected (and the connection still works).
account_idstring or nullThe chosen account, digits only (1234567890); null when none is chosen.
accountsarrayThe accounts the connected user can read (not the manager accounts themselves).
accounts[].account_idstringThe account id, digits only.
accounts[].namestring or nullIts name in Google Ads; null when it has none.
accounts[].currencystring or nullIts currency (EUR).
accounts[].login_account_idstringThe account we log in through: the manager account above it, or the account itself.

googleads.account_set

POST /rest/v1/googleads.account_set · MCP tool

Returns the chosen account after choosing the Google Ads account of the site, one of the accounts the connected Google user can read (googleads.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 account id from googleads.accounts (dashes are fine).

Example request

curl -X POST https://app.marketingtracer.com/rest/v1/googleads.account_set \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"site_id":"YOUR_SITE_ID","account_id":"330-000-0002"}'

Example response · Illustrative (ids and names made up).

{
  "data": {"account_id": "3300000002", "name": "Example shop", "currency": "USD"},
  "meta": {"site_id": "YOUR_SITE_ID"}
}

Response fields · in data:

FieldTypeWhat it is
account_idstringThe account now in use, digits only.
namestring or nullIts name in Google Ads.
currencystring or nullIts currency.

googleads.disconnect

POST /rest/v1/googleads.disconnect · MCP tool

Returns connected false after disconnecting Google Ads from the site (the Google user and the chosen 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/googleads.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 and agencies

The Google Ads API on your own domain. One white label key for every client site.

The API and MCP server run on your custom white label domain just like the dashboard. Owners and admins can create one white label key (mtw_…) that covers every client site at 600 calls per minute. Personal keys (mtk_…) run at 60 calls per minute with the same site access as your login.

When a client signs in on your domain to connect Google Ads or link Claude and ChatGPT over OAuth, the login screen shows your agency's name and logo in your brand colors. You also control per user role whether clients can see the MCP page.

White label SEO platform
API hubAll MarketingTracer REST API topics MCP serverAsk Claude, ChatGPT or Cursor across all tools Google Analytics 4 APISessions, channels, landing pages and conversions

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

Frequently asked questions about the Google Ads API

Account connections, reporting calculations, rate limits and how the REST API and MCP tools work.

Does MarketingTracer ever change anything in my Google Ads account?

No. Every call to Google Ads reads reporting data, so neither the REST API nor the MCP server can edit a bid, daily budget, campaign status, keyword or ad. In the MCP server, only the eight get_googleads_* read tools are available. Two REST write endpoints (googleads.account_set and googleads.disconnect) select or remove which Google Ads account is linked to the site in MarketingTracer.

How do I connect a client's Google Ads account or a manager account?

Sign in with Google once on the site's Google Ads page in the app. Then call googleads.accounts to list every client account that Google login can read, along with its currency and manager login_account_id. Pass the chosen 10-digit account_id (digits only or formatted with dashes) to googleads.account_set, and all report calls for that site will query that client account.

Why do ratio metrics like CTR and ROAS match the totals in Google Ads?

We calculate every ratio from the summed totals of the full period rather than averaging daily percentages. That applies to ctr_pct, average_cpc, conversion_rate_pct, cost_per_conversion, roas and absolute_top_impression_pct. When a denominator is zero, such as cost_per_conversion on a campaign with zero conversions, the API returns null.

What is the difference between googleads.keywords and googleads.search_terms?

googleads.keywords lists the bidded keywords inside each ad group, with their parent campaign, current status, match_type (exact, phrase or broad) and Google's 1-to-10 quality_score. googleads.search_terms lists the actual words people typed on Google when your ads appeared. If the same search term matched keywords in more than one ad group, googleads.search_terms sums its clicks and impressions along with cost and conversions into one row.

What is the difference between conversions and all_conversions?

Each row in googleads.conversions gives conversions and conversion_value for the primary actions in your main Conversions column in Google Ads. Those numbers can have decimals when your account uses data-driven attribution. all_conversions and all_conversion_value count every measured conversion action, such as secondary actions you track for observation.

Which errors can the Google Ads endpoints return?

When Google Ads is not connected for the site, or when the Google login was revoked, the API returns HTTP 409 with code not_connected. A connected Google login that has no Google Ads account selected yet returns HTTP 409 with code no_account. Invalid date ranges or pagination cursors return 400 (invalid_argument or invalid_cursor). Exceeding the rate limit returns 429 with a Retry-After header, and an upstream failure from Google Ads returns 502 (google_error).

What is the rate limit and what does API access cost?

API and MCP access are in every plan at no extra cost. A personal key (mtk_…) allows 60 calls per minute across the REST API and the MCP server combined. White label keys (mtw_…) run on your own white label domain and allow 600 calls per minute across every site in that white label. You can create several named keys on the MCP page in the app and revoke any key right away.