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 ormtw_…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"
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.
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 daysCross-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.
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.
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
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
from | string, YYYY-MM-DD | First day of the period, YYYY-MM-DD; give it together with to. |
to | string, YYYY-MM-DD | Last day of the period, YYYY-MM-DD (yesterday at the latest); give it together with from. At most 366 days. |
days | integer, 1 to 366, default 28 | Without from and to: the last this many days up to yesterday. Defaults to 28. |
compare | one of previous_period, previous_year | What the previous figures are: previous_period (the same number of days just before) or previous_year (the same days 52 weeks earlier, same weekdays; for periods up to 364 days). Defaults to previous_period. |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/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:
| Field | Type | What it is |
|---|---|---|
compare | string | previous_period or previous_year: what the previous figures are. |
clicks | object | Clicks in the period, against the previous period. |
clicks.value | number or null | This period; null when it does not apply. |
clicks.previous | number or null | The previous period; null when it does not apply. |
clicks.change | number or null | value minus previous. |
clicks.change_pct | number or null | The change in percent of previous; null when previous is 0 or null. |
impressions | object | Impressions in the period, against the previous period. |
impressions.value | number or null | This period; null when it does not apply. |
impressions.previous | number or null | The previous period; null when it does not apply. |
impressions.change | number or null | value minus previous. |
impressions.change_pct | number or null | The change in percent of previous; null when previous is 0 or null. |
ctr_pct | object | CTR, 0-100, in the period, against the previous period. |
ctr_pct.value | number or null | This period; null when it does not apply. |
ctr_pct.previous | number or null | The previous period; null when it does not apply. |
ctr_pct.change | number or null | value minus previous, in percentage points. |
ctr_pct.change_pct | number or null | The change in percent of previous; null when previous is 0 or null. |
cost | object | Cost in the period, against the previous period. |
cost.value | number or null | This period; null when it does not apply. |
cost.previous | number or null | The previous period; null when it does not apply. |
cost.change | number or null | value minus previous. |
cost.change_pct | number or null | The change in percent of previous; null when previous is 0 or null. |
average_cpc | object | Cost per click in the period, against the previous period. |
average_cpc.value | number or null | This period; null when it does not apply. |
average_cpc.previous | number or null | The previous period; null when it does not apply. |
average_cpc.change | number or null | value minus previous. |
average_cpc.change_pct | number or null | The change in percent of previous; null when previous is 0 or null. |
conversions | object | Conversions in the period, against the previous period. |
conversions.value | number or null | This period; null when it does not apply. |
conversions.previous | number or null | The previous period; null when it does not apply. |
conversions.change | number or null | value minus previous. |
conversions.change_pct | number or null | The change in percent of previous; null when previous is 0 or null. |
conversion_rate_pct | object | Conversion rate, 0-100, in the period, against the previous period. |
conversion_rate_pct.value | number or null | This period; null when it does not apply. |
conversion_rate_pct.previous | number or null | The previous period; null when it does not apply. |
conversion_rate_pct.change | number or null | value minus previous, in percentage points. |
conversion_rate_pct.change_pct | number or null | The change in percent of previous; null when previous is 0 or null. |
cost_per_conversion | object | Cost per conversion in the period, against the previous period. |
cost_per_conversion.value | number or null | This period; null when it does not apply. |
cost_per_conversion.previous | number or null | The previous period; null when it does not apply. |
cost_per_conversion.change | number or null | value minus previous. |
cost_per_conversion.change_pct | number or null | The change in percent of previous; null when previous is 0 or null. |
conversion_value | object | Conversion value in the period, against the previous period. |
conversion_value.value | number or null | This period; null when it does not apply. |
conversion_value.previous | number or null | The previous period; null when it does not apply. |
conversion_value.change | number or null | value minus previous. |
conversion_value.change_pct | number or null | The change in percent of previous; null when previous is 0 or null. |
roas | object | ROAS (conversion value / cost) in the period, against the previous period. |
roas.value | number or null | This period; null when it does not apply. |
roas.previous | number or null | The previous period; null when it does not apply. |
roas.change | number or null | value minus previous. |
roas.change_pct | number or null | The change in percent of previous; null when previous is 0 or null. |
absolute_top_impression_pct | object | Absolute top impression share, 0-100, in the period, against the previous period. |
absolute_top_impression_pct.value | number or null | This period; null when it does not apply. |
absolute_top_impression_pct.previous | number or null | The previous period; null when it does not apply. |
absolute_top_impression_pct.change | number or null | value minus previous, in percentage points. |
absolute_top_impression_pct.change_pct | number or null | The change in percent of previous; null when previous is 0 or null. |
daily | array | Per day of the period, oldest first, with all metrics, next to the matching day of the previous period. |
daily[].date | string | The day, YYYY-MM-DD. |
daily[].clicks | integer | Clicks. |
daily[].impressions | integer | Impressions. |
daily[].ctr_pct | number or null | Clicks as a share of impressions, 0-100; null without impressions. |
daily[].cost | number | Cost, in the currency of the Google Ads account (meta.currency). |
daily[].average_cpc | number or null | Cost per click; null without clicks. |
daily[].conversions | number | Conversions (the conversion actions counted in Conversions in Google Ads; can be fractional with data-driven attribution). |
daily[].conversion_rate_pct | number or null | Conversions as a share of interactions (clicks, calls, video views), 0-100; null without interactions. |
daily[].cost_per_conversion | number or null | Cost per conversion; null without conversions. |
daily[].conversion_value | number | Value of the conversions, in the account currency. |
daily[].roas | number or null | Return on ad spend: conversion_value divided by cost (3.5 = 3.5 times the cost back); null without cost. |
daily[].absolute_top_impression_pct | number or null | Share of the search impressions shown as the very first ad above the results, 0-100; null without impressions. |
daily[].previous_date | string | The matching day of the previous period, YYYY-MM-DD. |
daily[].previous | object | The same figures on previous_date. |
daily[].previous.clicks | integer | Clicks. |
daily[].previous.impressions | integer | Impressions. |
daily[].previous.ctr_pct | number or null | Clicks as a share of impressions, 0-100; null without impressions. |
daily[].previous.cost | number | Cost, in the currency of the Google Ads account (meta.currency). |
daily[].previous.average_cpc | number or null | Cost per click; null without clicks. |
daily[].previous.conversions | number | Conversions (the conversion actions counted in Conversions in Google Ads; can be fractional with data-driven attribution). |
daily[].previous.conversion_rate_pct | number or null | Conversions as a share of interactions (clicks, calls, video views), 0-100; null without interactions. |
daily[].previous.cost_per_conversion | number or null | Cost per conversion; null without conversions. |
daily[].previous.conversion_value | number | Value of the conversions, in the account currency. |
daily[].previous.roas | number or null | Return on ad spend: conversion_value divided by cost (3.5 = 3.5 times the cost back); null without cost. |
daily[].previous.absolute_top_impression_pct | number or null | Share 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
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
from | string, YYYY-MM-DD | First day of the period, YYYY-MM-DD; give it together with to. |
to | string, YYYY-MM-DD | Last day of the period, YYYY-MM-DD (yesterday at the latest); give it together with from. At most 366 days. |
days | integer, 1 to 366, default 28 | Without from and to: the last this many days up to yesterday. Defaults to 28. |
compare | one of previous_period, previous_year | What the previous figures are: previous_period (the same number of days just before) or previous_year (the same days 52 weeks earlier, same weekdays; for periods up to 364 days). Defaults to previous_period. |
limit | integer, 1 to 500, default 100 | Items per call. |
cursor | string | meta.next_cursor of the previous call, for the next page. |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/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:
| Field | Type | What it is |
|---|---|---|
campaign_id | string | The campaign id in Google Ads. |
campaign | string | The campaign name. |
status | string or null | enabled, paused or removed (now, not in the period). |
channel_type | string or null | search, display, shopping, video, performance_max, … |
daily_budget | number or null | The 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_pct | number or null | Impressions 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_pct | number or null | The share of possible Search impressions missed because the budget ran out, 0-100; null like search_impression_share_pct. |
search_lost_rank_pct | number or null | The share of possible Search impressions missed because of ad rank (bid and quality), 0-100; null like search_impression_share_pct. |
clicks | integer | Clicks. |
impressions | integer | Impressions. |
ctr_pct | number or null | Clicks as a share of impressions, 0-100; null without impressions. |
cost | number | Cost, in the currency of the Google Ads account (meta.currency). |
average_cpc | number or null | Cost per click; null without clicks. |
conversions | number | Conversions (the conversion actions counted in Conversions in Google Ads; can be fractional with data-driven attribution). |
conversion_rate_pct | number or null | Conversions as a share of interactions (clicks, calls, video views), 0-100; null without interactions. |
cost_per_conversion | number or null | Cost per conversion; null without conversions. |
conversion_value | number | Value of the conversions, in the account currency. |
roas | number or null | Return on ad spend: conversion_value divided by cost (3.5 = 3.5 times the cost back); null without cost. |
absolute_top_impression_pct | number or null | Share of the search impressions shown as the very first ad above the results, 0-100; null without impressions. |
share_pct | number or null | Share of the clicks of the whole list, 0-100; null when the list has no clicks. |
previous | object or null | The same figures in the previous period; null when it had no impressions then. |
previous.clicks | integer | Clicks. |
previous.impressions | integer | Impressions. |
previous.ctr_pct | number or null | Clicks as a share of impressions, 0-100; null without impressions. |
previous.cost | number | Cost, in the currency of the Google Ads account (meta.currency). |
previous.average_cpc | number or null | Cost per click; null without clicks. |
previous.conversions | number | Conversions (the conversion actions counted in Conversions in Google Ads; can be fractional with data-driven attribution). |
previous.conversion_rate_pct | number or null | Conversions as a share of interactions (clicks, calls, video views), 0-100; null without interactions. |
previous.cost_per_conversion | number or null | Cost per conversion; null without conversions. |
previous.conversion_value | number | Value of the conversions, in the account currency. |
previous.roas | number or null | Return on ad spend: conversion_value divided by cost (3.5 = 3.5 times the cost back); null without cost. |
previous.absolute_top_impression_pct | number or null | Share 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
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
from | string, YYYY-MM-DD | First day of the period, YYYY-MM-DD; give it together with to. |
to | string, YYYY-MM-DD | Last day of the period, YYYY-MM-DD (yesterday at the latest); give it together with from. At most 366 days. |
days | integer, 1 to 366, default 28 | Without from and to: the last this many days up to yesterday. Defaults to 28. |
compare | one of previous_period, previous_year | What the previous figures are: previous_period (the same number of days just before) or previous_year (the same days 52 weeks earlier, same weekdays; for periods up to 364 days). Defaults to previous_period. |
limit | integer, 1 to 500, default 100 | Items per call. |
cursor | string | meta.next_cursor of the previous call, for the next page. |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/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:
| Field | Type | What it is |
|---|---|---|
ad_group_id | string | The ad group id in Google Ads. |
ad_group | string | The ad group name. |
status | string or null | enabled, paused or removed (now, not in the period). |
campaign_id | string | The campaign it is in. |
campaign | string | The campaign name. |
clicks | integer | Clicks. |
impressions | integer | Impressions. |
ctr_pct | number or null | Clicks as a share of impressions, 0-100; null without impressions. |
cost | number | Cost, in the currency of the Google Ads account (meta.currency). |
average_cpc | number or null | Cost per click; null without clicks. |
conversions | number | Conversions (the conversion actions counted in Conversions in Google Ads; can be fractional with data-driven attribution). |
conversion_rate_pct | number or null | Conversions as a share of interactions (clicks, calls, video views), 0-100; null without interactions. |
cost_per_conversion | number or null | Cost per conversion; null without conversions. |
conversion_value | number | Value of the conversions, in the account currency. |
roas | number or null | Return on ad spend: conversion_value divided by cost (3.5 = 3.5 times the cost back); null without cost. |
absolute_top_impression_pct | number or null | Share of the search impressions shown as the very first ad above the results, 0-100; null without impressions. |
share_pct | number or null | Share of the clicks of the whole list, 0-100; null when the list has no clicks. |
previous | object or null | The same figures in the previous period; null when it had no impressions then. |
previous.clicks | integer | Clicks. |
previous.impressions | integer | Impressions. |
previous.ctr_pct | number or null | Clicks as a share of impressions, 0-100; null without impressions. |
previous.cost | number | Cost, in the currency of the Google Ads account (meta.currency). |
previous.average_cpc | number or null | Cost per click; null without clicks. |
previous.conversions | number | Conversions (the conversion actions counted in Conversions in Google Ads; can be fractional with data-driven attribution). |
previous.conversion_rate_pct | number or null | Conversions as a share of interactions (clicks, calls, video views), 0-100; null without interactions. |
previous.cost_per_conversion | number or null | Cost per conversion; null without conversions. |
previous.conversion_value | number | Value of the conversions, in the account currency. |
previous.roas | number or null | Return on ad spend: conversion_value divided by cost (3.5 = 3.5 times the cost back); null without cost. |
previous.absolute_top_impression_pct | number or null | Share 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
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
from | string, YYYY-MM-DD | First day of the period, YYYY-MM-DD; give it together with to. |
to | string, YYYY-MM-DD | Last day of the period, YYYY-MM-DD (yesterday at the latest); give it together with from. At most 366 days. |
days | integer, 1 to 366, default 28 | Without from and to: the last this many days up to yesterday. Defaults to 28. |
compare | one of previous_period, previous_year | What the previous figures are: previous_period (the same number of days just before) or previous_year (the same days 52 weeks earlier, same weekdays; for periods up to 364 days). Defaults to previous_period. |
limit | integer, 1 to 500, default 100 | Items per call. |
cursor | string | meta.next_cursor of the previous call, for the next page. |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/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:
| Field | Type | What it is |
|---|---|---|
search_term | string | The search term as typed. |
clicks | integer | Clicks. |
impressions | integer | Impressions. |
ctr_pct | number or null | Clicks as a share of impressions, 0-100; null without impressions. |
cost | number | Cost, in the currency of the Google Ads account (meta.currency). |
average_cpc | number or null | Cost per click; null without clicks. |
conversions | number | Conversions (the conversion actions counted in Conversions in Google Ads; can be fractional with data-driven attribution). |
conversion_rate_pct | number or null | Conversions as a share of interactions (clicks, calls, video views), 0-100; null without interactions. |
cost_per_conversion | number or null | Cost per conversion; null without conversions. |
conversion_value | number | Value of the conversions, in the account currency. |
roas | number or null | Return on ad spend: conversion_value divided by cost (3.5 = 3.5 times the cost back); null without cost. |
absolute_top_impression_pct | number or null | Share of the search impressions shown as the very first ad above the results, 0-100; null without impressions. |
share_pct | number or null | Share of the clicks of the whole list, 0-100; null when the list has no clicks. |
previous | object or null | The same figures in the previous period; null when it had no impressions then. |
previous.clicks | integer | Clicks. |
previous.impressions | integer | Impressions. |
previous.ctr_pct | number or null | Clicks as a share of impressions, 0-100; null without impressions. |
previous.cost | number | Cost, in the currency of the Google Ads account (meta.currency). |
previous.average_cpc | number or null | Cost per click; null without clicks. |
previous.conversions | number | Conversions (the conversion actions counted in Conversions in Google Ads; can be fractional with data-driven attribution). |
previous.conversion_rate_pct | number or null | Conversions as a share of interactions (clicks, calls, video views), 0-100; null without interactions. |
previous.cost_per_conversion | number or null | Cost per conversion; null without conversions. |
previous.conversion_value | number | Value of the conversions, in the account currency. |
previous.roas | number or null | Return on ad spend: conversion_value divided by cost (3.5 = 3.5 times the cost back); null without cost. |
previous.absolute_top_impression_pct | number or null | Share 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
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
from | string, YYYY-MM-DD | First day of the period, YYYY-MM-DD; give it together with to. |
to | string, YYYY-MM-DD | Last day of the period, YYYY-MM-DD (yesterday at the latest); give it together with from. At most 366 days. |
days | integer, 1 to 366, default 28 | Without from and to: the last this many days up to yesterday. Defaults to 28. |
compare | one of previous_period, previous_year | What the previous figures are: previous_period (the same number of days just before) or previous_year (the same days 52 weeks earlier, same weekdays; for periods up to 364 days). Defaults to previous_period. |
limit | integer, 1 to 500, default 100 | Items per call. |
cursor | string | meta.next_cursor of the previous call, for the next page. |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/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:
| Field | Type | What it is |
|---|---|---|
keyword | string | The keyword as set in Google Ads. |
match_type | string or null | exact, phrase or broad. |
status | string or null | enabled, paused or removed (now, not in the period). |
quality_score | integer or null | Google's quality score now, 1-10; null when Google has too little data. |
ad_group_id | string | The ad group it is in. |
ad_group | string | The ad group name. |
campaign_id | string | The campaign it is in. |
campaign | string | The campaign name. |
clicks | integer | Clicks. |
impressions | integer | Impressions. |
ctr_pct | number or null | Clicks as a share of impressions, 0-100; null without impressions. |
cost | number | Cost, in the currency of the Google Ads account (meta.currency). |
average_cpc | number or null | Cost per click; null without clicks. |
conversions | number | Conversions (the conversion actions counted in Conversions in Google Ads; can be fractional with data-driven attribution). |
conversion_rate_pct | number or null | Conversions as a share of interactions (clicks, calls, video views), 0-100; null without interactions. |
cost_per_conversion | number or null | Cost per conversion; null without conversions. |
conversion_value | number | Value of the conversions, in the account currency. |
roas | number or null | Return on ad spend: conversion_value divided by cost (3.5 = 3.5 times the cost back); null without cost. |
absolute_top_impression_pct | number or null | Share of the search impressions shown as the very first ad above the results, 0-100; null without impressions. |
share_pct | number or null | Share of the clicks of the whole list, 0-100; null when the list has no clicks. |
previous | object or null | The same figures in the previous period; null when it had no impressions then. |
previous.clicks | integer | Clicks. |
previous.impressions | integer | Impressions. |
previous.ctr_pct | number or null | Clicks as a share of impressions, 0-100; null without impressions. |
previous.cost | number | Cost, in the currency of the Google Ads account (meta.currency). |
previous.average_cpc | number or null | Cost per click; null without clicks. |
previous.conversions | number | Conversions (the conversion actions counted in Conversions in Google Ads; can be fractional with data-driven attribution). |
previous.conversion_rate_pct | number or null | Conversions as a share of interactions (clicks, calls, video views), 0-100; null without interactions. |
previous.cost_per_conversion | number or null | Cost per conversion; null without conversions. |
previous.conversion_value | number | Value of the conversions, in the account currency. |
previous.roas | number or null | Return on ad spend: conversion_value divided by cost (3.5 = 3.5 times the cost back); null without cost. |
previous.absolute_top_impression_pct | number or null | Share 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
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
from | string, YYYY-MM-DD | First day of the period, YYYY-MM-DD; give it together with to. |
to | string, YYYY-MM-DD | Last day of the period, YYYY-MM-DD (yesterday at the latest); give it together with from. At most 366 days. |
days | integer, 1 to 366, default 28 | Without from and to: the last this many days up to yesterday. Defaults to 28. |
compare | one of previous_period, previous_year | What the previous figures are: previous_period (the same number of days just before) or previous_year (the same days 52 weeks earlier, same weekdays; for periods up to 364 days). Defaults to previous_period. |
limit | integer, 1 to 500, default 100 | Items per call. |
cursor | string | meta.next_cursor of the previous call, for the next page. |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/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:
| Field | Type | What it is |
|---|---|---|
device | string | mobile, desktop, tablet, connected_tv or other. |
clicks | integer | Clicks. |
impressions | integer | Impressions. |
ctr_pct | number or null | Clicks as a share of impressions, 0-100; null without impressions. |
cost | number | Cost, in the currency of the Google Ads account (meta.currency). |
average_cpc | number or null | Cost per click; null without clicks. |
conversions | number | Conversions (the conversion actions counted in Conversions in Google Ads; can be fractional with data-driven attribution). |
conversion_rate_pct | number or null | Conversions as a share of interactions (clicks, calls, video views), 0-100; null without interactions. |
cost_per_conversion | number or null | Cost per conversion; null without conversions. |
conversion_value | number | Value of the conversions, in the account currency. |
roas | number or null | Return on ad spend: conversion_value divided by cost (3.5 = 3.5 times the cost back); null without cost. |
absolute_top_impression_pct | number or null | Share of the search impressions shown as the very first ad above the results, 0-100; null without impressions. |
share_pct | number or null | Share of the clicks of the whole list, 0-100; null when the list has no clicks. |
previous | object or null | The same figures in the previous period; null when it had no impressions then. |
previous.clicks | integer | Clicks. |
previous.impressions | integer | Impressions. |
previous.ctr_pct | number or null | Clicks as a share of impressions, 0-100; null without impressions. |
previous.cost | number | Cost, in the currency of the Google Ads account (meta.currency). |
previous.average_cpc | number or null | Cost per click; null without clicks. |
previous.conversions | number | Conversions (the conversion actions counted in Conversions in Google Ads; can be fractional with data-driven attribution). |
previous.conversion_rate_pct | number or null | Conversions as a share of interactions (clicks, calls, video views), 0-100; null without interactions. |
previous.cost_per_conversion | number or null | Cost per conversion; null without conversions. |
previous.conversion_value | number | Value of the conversions, in the account currency. |
previous.roas | number or null | Return on ad spend: conversion_value divided by cost (3.5 = 3.5 times the cost back); null without cost. |
previous.absolute_top_impression_pct | number or null | Share 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
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
from | string, YYYY-MM-DD | First day of the period, YYYY-MM-DD; give it together with to. |
to | string, YYYY-MM-DD | Last day of the period, YYYY-MM-DD (yesterday at the latest); give it together with from. At most 366 days. |
days | integer, 1 to 366, default 28 | Without from and to: the last this many days up to yesterday. Defaults to 28. |
compare | one of previous_period, previous_year | What the previous figures are: previous_period (the same number of days just before) or previous_year (the same days 52 weeks earlier, same weekdays; for periods up to 364 days). Defaults to previous_period. |
limit | integer, 1 to 500, default 100 | Items per call. |
cursor | string | meta.next_cursor of the previous call, for the next page. |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/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:
| Field | Type | What it is |
|---|---|---|
conversion_action | string | The name of the conversion action in Google Ads. |
conversions | number | Conversions (only when the action counts in Conversions). |
conversion_value | number | Their value, in the account currency. |
all_conversions | number | All conversions of this action. |
all_conversion_value | number | Their value. |
previous | object or null | The same figures in the previous period; null when the action had no conversions then. |
previous.conversions | number | Conversions. |
previous.conversion_value | number | Conversion value. |
previous.all_conversions | number | All conversions. |
previous.all_conversion_value | number | All 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
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/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:
| Field | Type | What it is |
|---|---|---|
connected | boolean | Whether a Google user with Google Ads access is connected (and the connection still works). |
account_id | string or null | The chosen account, digits only (1234567890); null when none is chosen. |
accounts | array | The accounts the connected user can read (not the manager accounts themselves). |
accounts[].account_id | string | The account id, digits only. |
accounts[].name | string or null | Its name in Google Ads; null when it has none. |
accounts[].currency | string or null | Its currency (EUR). |
accounts[].login_account_id | string | The 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
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
account_id (required) | string | The 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:
| Field | Type | What it is |
|---|---|---|
account_id | string | The account now in use, digits only. |
name | string or null | Its name in Google Ads. |
currency | string or null | Its 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
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/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:
| Field | Type | What it is |
|---|---|---|
connected | boolean | Always false. |
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 platformFree 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
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.