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.

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)pattern: ^[\d-]+$
reason string Required Why this tool call is neededminLength: 1, maxLength: 500
Optional parameters (8)
NameTypeRequiredDescription
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
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 IDpattern: ^\d+$
ad_group_id string Optional Filter to a specific ad group IDpattern: ^\d+$

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