`google_ads_get_search_terms_report`

Get Google Ads Search Terms Report

Google

Description

Get actual search queries that triggered ads, with performance metrics and keyword match status. Google may not disclose all terms for privacy. Supports segments parameter (e.g., ad_network_type) for channel-level breakdown — use to compare Search vs Search Partners per search term. Always fetches fresh data. Conversion breakdown and landing page lookups are opt-in to control response size. For Performance Max campaigns, set pmax_search_categories=true to get search category insights (grouped themes) instead of individual search terms.

Read-onlyIdempotentOpen-world

Usage

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "google_ads_get_search_terms_report",
    "arguments": {
      "customer_id": "1234567890",
      "date_preset": "LAST_7_DAYS",
      "reason": "Search term analysis"
    }
  }
}

hopkin google search-terms-report get

Flag	Type	Required	Description
`--customer-id`	`string`	Required	The Google Ads Customer ID (10 digits, with or without dashes)
`--login-customer-id`	`string`	Optional	MCC (Manager) Customer ID; required for managed accounts
`--date-preset`	`string`	Optional	Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH
`--date-range`	`object`	Optional	Custom date range {start_date, end_date} in YYYY-MM-DD
`--campaign`	`string`	Optional	Filter to a specific campaign ID
`--ad-group-id`	`string`	Optional	Filter to a specific ad group ID
`--search-term-status`	`array`	Optional	Filter by search term status: ADDED, EXCLUDED, ADDED_EXCLUDED, NONE
`--limit`	`integer`	Optional	Maximum number of rows to return (1-1000, default 100)
`--order-by`	`string`	Optional	Sort by metric (descending): impressions, clicks, cost, conversions, ctr
`--include-all-conversions`	`boolean`	Optional	When true, includes an additional all-conversions breakdown (metrics.all_conversions, all_conversions_value, value_per_all_conversions) segmented by conversion_action_name. This captures ALL conversion actions including those not marked "Include in Conversions".
`--include-conversion-breakdown`	`boolean`	Optional	When true, runs a parallel query to include conversion breakdown by ad group and conversion action. Adds significant response size — omit when response size is a concern. Default: false.
`--include-landing-pages`	`boolean`	Optional	When true, runs a parallel query against ad_group_ad to fetch final_urls for each ad group in the results. Returns landing_pages_by_ad_group map keyed by ad_group_id. Default: false.
`--pmax-search-categories`	`boolean`	Optional	When true, queries campaign_search_term_insight for PMax search category data (grouped themes, not individual queries). ad_group_id and search_term_status are ignored in this mode. Default: false.
`--segments`	`array`	Optional	Segments to break down by (e.g., ad_network_type, device). Use ad_network_type to split search term metrics by channel (SEARCH vs SEARCH_PARTNERS). Ignored when pmax_search_categories is true.

{
  "mcpServers": {
    "google-ads": {
      "url": "https://mcp.hopkin.ai/google-ads/mcp",
      "transport": "sse"
    }
  }
}

Top search terms
New terms only
With landing pages
PMax search categories
By network channel

Parameters

Name	Type	Required	Description
`customer_id`	`string`	Required	The Google Ads Customer ID (10 digits, with or without dashes)pattern: ^[\d-]+$
`reason`	`string`	Required	Why this tool call is neededminLength: 1, maxLength: 500

Optional parameters (13)

Name	Type	Required	Description
`login_customer_id`	`string`	Optional	MCC (Manager) Customer ID; required for managed accountspattern: ^[\d-]+$
`date_preset`	`string`	Optional	Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH `TODAY` `YESTERDAY` `LAST_7_DAYS` `LAST_30_DAYS` `THIS_MONTH` `LAST_MONTH`
`date_range`	`object`	Optional	Custom date range {start_date, end_date} in YYYY-MM-DD
`campaign_id`	`string`	Optional	Filter to a specific campaign IDpattern: ^\d+$
`ad_group_id`	`string`	Optional	Filter to a specific ad group IDpattern: ^\d+$
`search_term_status`	`array`	Optional	Filter by search term status: ADDED, EXCLUDED, ADDED_EXCLUDED, NONE
`limit`	`integer`	Optional	Maximum number of rows to return (1-1000, default 100)min: 1, max: 1000
`order_by`	`string`	Optional	Sort by metric (descending): impressions, clicks, cost, conversions, ctr `impressions` `clicks` `cost` `conversions` `ctr`
`include_all_conversions`	`boolean`	Optional	When true, includes an additional all-conversions breakdown (metrics.all_conversions, all_conversions_value, value_per_all_conversions) segmented by conversion_action_name. This captures ALL conversion actions including those not marked "Include in Conversions".
`include_conversion_breakdown`	`boolean`	Optional	When true, runs a parallel query to include conversion breakdown by ad group and conversion action. Adds significant response size — omit when response size is a concern. Default: false.
`include_landing_pages`	`boolean`	Optional	When true, runs a parallel query against ad_group_ad to fetch final_urls for each ad group in the results. Returns landing_pages_by_ad_group map keyed by ad_group_id. Default: false.
`pmax_search_categories`	`boolean`	Optional	When true, queries campaign_search_term_insight for PMax search category data (grouped themes, not individual queries). ad_group_id and search_term_status are ignored in this mode. Default: false.
`segments`	`array`	Optional	Segments to break down by (e.g., ad_network_type, device). Use ad_network_type to split search term metrics by channel (SEARCH vs SEARCH_PARTNERS). Ignored when pmax_search_categories is true.

Examples

Top search terms

{
  "customer_id": "1234567890",
  "date_preset": "LAST_7_DAYS",
  "reason": "Search term analysis"
}

hopkin google search-terms-report get --customer-id 1234567890 --date-preset LAST_7_DAYS

New terms only

{
  "customer_id": "1234567890",
  "date_preset": "LAST_7_DAYS",
  "search_term_status": [
    "NONE"
  ],
  "order_by": "conversions",
  "reason": "Find new converting search terms"
}

hopkin google search-terms-report get --customer-id 1234567890 --date-preset LAST_7_DAYS --search-term-status NONE --order-by conversions

With landing pages

{
  "customer_id": "1234567890",
  "date_preset": "LAST_7_DAYS",
  "include_landing_pages": true,
  "reason": "Find which landing pages top search terms go to"
}

hopkin google search-terms-report get --customer-id 1234567890 --date-preset LAST_7_DAYS --include-landing-pages true

PMax search categories

{
  "customer_id": "1234567890",
  "campaign_id": "5555555555",
  "date_preset": "LAST_30_DAYS",
  "pmax_search_categories": true,
  "reason": "PMax search category analysis"
}

hopkin google search-terms-report get --customer-id 1234567890 --campaign 5555555555 --date-preset LAST_30_DAYS --pmax-search-categories true

By network channel

{
  "customer_id": "1234567890",
  "date_preset": "LAST_30_DAYS",
  "segments": [
    "ad_network_type"
  ],
  "reason": "Search terms by ad network"
}

hopkin google search-terms-report get --customer-id 1234567890 --date-preset LAST_30_DAYS --segments ad_network_type