google_ads_get_insights

Get Google Ads Insights

Google

Description

Retrieve performance metrics using GAQL with full control over metrics, segments, levels, and date ranges. Always fetches fresh data. Default metrics include the supported Demand Gen Platform Comparable conversion family. Custom metrics accept Platform Comparable columns with or without the metrics. prefix (for example platform_comparable_conversions or metrics.platform_comparable_conversions). Supports device breakdowns, ad_network_type channel analysis, and search impression share diagnostics. For standard analysis, prefer google_ads_get_performance_report; use this only for custom metric selection, search impression share diagnostics, ad_network_type channel breakdowns, or segment combinations not available in the performance report. For geographic data, use google_ads_get_geo_performance instead. Conversion action segments automatically remove incompatible cost-based metrics. Budget-lost impression share variants are campaign-level only. Paginated: returns up to limit rows (default 30, max 1000) in a stable order (entity ids, then segment values); count is the total across all pages. When pagination.hasMore is true, call again with the same parameters and cursor set to pagination.nextCursor until hasMore is false. To get every row, follow the cursor rather than raising limit: a larger page can exceed MCP client response limits.

Read-onlyIdempotentOpen-world

Usage

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "google_ads_get_insights",
    "arguments": {
      "customer_id": "1234567890",
      "date_preset": "LAST_30_DAYS",
      "metrics": [
        "all_conversions",
        "all_conversions_value",
        "value_per_all_conversions"
      ],
      "segments": [
        "conversion_action_name"
      ],
      "reason": "All conversions breakdown by action"
    }
  }
}

Parameters

NameTypeRequiredDescription
customer_id string Required The Google Ads Customer ID (10 digits, with or without dashes)maxLength: 20, pattern: ^[\d-]+$
reason string Required Why this tool call is neededminLength: 1, maxLength: 500
Optional parameters (11)
NameTypeRequiredDescription
login_customer_id string Optional MCC (Manager) Customer ID; required for managed accountsmaxLength: 20, pattern: ^[\d-]+$
date_preset string Optional Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH. LAST_7_DAYS / LAST_30_DAYS are the 7 / 30 complete days ending yesterday (account time zone), as in Google Ads; THIS_MONTH runs through today.
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
level string Optional Report level (default: ACCOUNT): ACCOUNT, CAMPAIGN, AD_GROUP, AD
ACCOUNT CAMPAIGN AD_GROUP AD
metrics array Optional Metrics to retrieve (defaults to standard set). Demand Gen Platform Comparable columns are accepted with or without the metrics. prefix, e.g. platform_comparable_conversions or metrics.platform_comparable_conversions. These Demand Gen-only columns include view-through conversions; see https://support.google.com/google-ads/answer/15299024.
segments array Optional Segments to break down by (e.g., date, device, ad_network_type). Use ad_network_type to see which channel delivered traffic (SEARCH, YOUTUBE_WATCH, DISPLAY, DISCOVER, etc.) — essential for Performance Max analysis.
campaign_id string Optional Filter to a specific campaign IDmaxLength: 20, pattern: ^\d+$
ad_group_id string Optional Filter to a specific ad group IDmaxLength: 20, pattern: ^\d+$
limit integer Optional Maximum rows per page (1-1000, default 30). count is the total across all pages; when pagination.hasMore is true, call again with cursor set to pagination.nextCursor. The default keeps a page within MCP client response limits: to get every row, follow nextCursor rather than raising limit.min: 1, max: 1000
cursor string Optional Opaque cursor from a previous response's pagination.nextCursor. Pass it with the same other parameters to fetch the next page; do not construct it.minLength: 1, maxLength: 4096
connection_id string Optional Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call <platform>_list_connections to discover available connection IDs.

Examples

All conversions by action

{
  "customer_id": "1234567890",
  "date_preset": "LAST_30_DAYS",
  "metrics": [
    "all_conversions",
    "all_conversions_value",
    "value_per_all_conversions"
  ],
  "segments": [
    "conversion_action_name"
  ],
  "reason": "All conversions breakdown by action"
}

hopkin google insights get --customer-id 1234567890 --date-preset LAST_30_DAYS --metrics all_conversions,all_conversions_value,value_per_all_conversions --segments conversion_action_name

Search impression share

{
  "customer_id": "1234567890",
  "date_preset": "LAST_7_DAYS",
  "level": "CAMPAIGN",
  "metrics": [
    "search_impression_share",
    "search_top_impression_share",
    "search_absolute_top_impression_share",
    "search_budget_lost_impression_share",
    "search_rank_lost_impression_share"
  ],
  "reason": "Search IS diagnostics"
}

hopkin google insights get --customer-id 1234567890 --date-preset LAST_7_DAYS --level CAMPAIGN --metrics search_impression_share,search_top_impression_share,search_absolute_top_impression_share,search_budget_lost_impression_share,search_rank_lost_impression_share

Device breakdown with custom metrics

{
  "customer_id": "1234567890",
  "date_preset": "LAST_30_DAYS",
  "level": "CAMPAIGN",
  "segments": [
    "device"
  ],
  "metrics": [
    "impressions",
    "clicks",
    "cost_micros",
    "conversions",
    "view_through_conversions"
  ],
  "reason": "Device breakdown with view-through conversions"
}

hopkin google insights get --customer-id 1234567890 --date-preset LAST_30_DAYS --level CAMPAIGN --segments device --metrics impressions,clicks,cost_micros,conversions,view_through_conversions

PMax channel breakdown

{
  "customer_id": "1234567890",
  "date_preset": "LAST_30_DAYS",
  "level": "CAMPAIGN",
  "segments": [
    "ad_network_type"
  ],
  "reason": "PMax channel-level performance breakdown"
}

hopkin google insights get --customer-id 1234567890 --date-preset LAST_30_DAYS --level CAMPAIGN --segments ad_network_type