google_ads_generate_keyword_forecast_metrics

Generate Google Ads Keyword Forecast Metrics

Google

Description

Forecast campaign performance for a set of keywords with budget and bidding config. Returns projected impressions, clicks, cost, CTR, conversions, and CPA. Supports MANUAL_CPC (requires default_max_cpc_bid_micros), MAXIMIZE_CLICKS, and MAXIMIZE_CONVERSIONS strategies. Budget is in micros (10000000 = $10). Examples: forecast a $50/day campaign with exact-match keywords, or compare BROAD vs EXACT match performance.

Read-onlyIdempotentOpen-world

Usage

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "google_ads_generate_keyword_forecast_metrics",
    "arguments": {
      "customer_id": "1234567890",
      "keywords": [
        {
          "text": "running shoes",
          "match_type": "EXACT"
        }
      ],
      "daily_budget_micros": 10000000,
      "default_max_cpc_bid_micros": 1500000,
      "bidding_strategy": "MANUAL_CPC",
      "reason": "Budget planning for new campaign"
    }
  }
}

Parameters

NameTypeRequiredDescription
customer_id string Required The Google Ads Customer ID (10 digits, with or without dashes)pattern: ^[\d-]+$
keywords array Required Keywords to get historical metrics for (1-200 keywords)
reason string Required Why this tool call is neededminLength: 1, maxLength: 500
Optional parameters (6)
NameTypeRequiredDescription
login_customer_id string Optional MCC (Manager) Customer ID; required for managed accountspattern: ^[\d-]+$
language string Optional ISO 639-1 language code (e.g. "en", "es"). Maps internally to languageConstants resource name.pattern: ^[a-z]{2}$
geo_targets array Optional ISO 3166-1 alpha-2 country codes (e.g. ["US", "GB"]). Maps internally to geoTargetConstants.
network string Optional Network: GOOGLE_SEARCH (default) or GOOGLE_SEARCH_AND_PARTNERS
GOOGLE_SEARCH GOOGLE_SEARCH_AND_PARTNERS
include_monthly_volumes boolean Optional When true, includes month-by-month search volume data. Default: false.
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

Manual CPC forecast

{
  "customer_id": "1234567890",
  "keywords": [
    {
      "text": "running shoes",
      "match_type": "EXACT"
    }
  ],
  "daily_budget_micros": 10000000,
  "default_max_cpc_bid_micros": 1500000,
  "bidding_strategy": "MANUAL_CPC",
  "reason": "Budget planning for new campaign"
}

hopkin google generate-keyword-forecast-metrics --customer-id 1234567890 --keywords [object Object] --daily-budget-micros 10000000 --default-max-cpc-bid-micros 1500000 --bidding-strategy MANUAL_CPC

Maximize clicks

{
  "customer_id": "1234567890",
  "keywords": [
    {
      "text": "yoga mat"
    },
    {
      "text": "yoga accessories"
    }
  ],
  "daily_budget_micros": 5000000,
  "bidding_strategy": "MAXIMIZE_CLICKS",
  "reason": "Estimate traffic potential"
}

hopkin google generate-keyword-forecast-metrics --customer-id 1234567890 --keywords [object Object],[object Object] --daily-budget-micros 5000000 --bidding-strategy MAXIMIZE_CLICKS

With date range

{
  "customer_id": "1234567890",
  "keywords": [
    {
      "text": "winter coats",
      "match_type": "BROAD"
    }
  ],
  "daily_budget_micros": 20000000,
  "default_max_cpc_bid_micros": 2000000,
  "forecast_start_date": "2025-11-01",
  "forecast_end_date": "2025-12-31",
  "reason": "Holiday season forecast"
}

hopkin google generate-keyword-forecast-metrics --customer-id 1234567890 --keywords [object Object] --daily-budget-micros 20000000 --default-max-cpc-bid-micros 2000000 --forecast-start-date 2025-11-01 --forecast-end-date 2025-12-31