`microsoft_ads_get_keyword_report`

Get Microsoft Ads Keyword Report

Microsoft

Description

Read-onlyOpen-world

Usage

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "microsoft_ads_get_keyword_report",
    "arguments": {}
  }
}

hopkin microsoft keyword-report get

Flag	Type	Required	Description
`--account`	`string`	Required	Microsoft Advertising account ID (AccountId). Required.
`--customer-id`	`string`	Optional	Customer/manager ID (CustomerId). Required when accessing accounts under a manager hierarchy.
`--date-range`	`object`	Optional	Custom date range. Provide either date_range or date_preset, not both.
`--date-preset`	`string`	Optional	Predefined date range. One of: Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear.
`--campaign-ids`	`array`	Optional	Filter to specific campaign IDs (up to 100). Accepts JSON array string or actual array.
`--ad-group-ids`	`array`	Optional	Filter to specific ad group IDs (up to 200). Accepts JSON array string or actual array.
`--keyword-match-type`	`string`	Optional	Filter to keywords bid on this match type (bid_match_type): Exact, Phrase, or Broad.
`--include-quality-score`	`boolean`	Optional	When true (default), includes QualityScore (1-10) plus three sub-component columns: ExpectedCtr, AdRelevance, and LandingPageExperience. Each sub-component is categorical: AboveAverage, Average, or BelowAverage.
`--include-all-conversions`	`boolean`	Optional	When true, includes an additional all_conversions block per row (all_conversions, all_revenue, all_cost_per_conversion, all_roas, view_through_conversions). This captures ALL conversion goals including those not marked "Include in Conversions" (e.g., view-through, non-bidding goals). Note: conversions is the bidding-set count only; all_conversions.all_conversions is every conversion goal — typically much larger for accounts with non-bidding goals.
`--breakdown-by-goal`	`boolean`	Optional	When true (default), runs a parallel GoalsAndFunnelsReport and returns goal_breakdown keyed by ad_group_id. Each entry is an array of per-goal rows with all_conversions, all_revenue, view_through_conversions, and assists. IMPORTANT: Because GoalsAndFunnelsReport only scopes down to ad-group level (Bing does not support keyword-level goal breakdown), the breakdown is at ad_group granularity — NOT per keyword. goal_breakdown_granularity will always be "ad_group" for this tool. Each keyword row can look up its parent ad-group's goal breakdown via goal_breakdown[ad_group_id]. Pass false to skip the parallel report when latency matters more than goal context.
`--aggregation`	`string`	Optional	Report aggregation period. Daily (default), Weekly, Monthly, or Summary (all dates collapsed).
`--limit`	`integer`	Optional	Page size: rows per page (1–10000, default 15). count is the total across all pages. When more rows remain the response carries nextCursor; pass it back as cursor to get the next page. Large pages can exceed what an MCP client accepts in one response (roughly 60 rows, fewer with include_all_conversions, and breakdown_by_goal adds ~5K characters per ad group on the page); to cover every keyword, follow nextCursor rather than raising limit.
`--cursor`	`string`	Optional	Opaque pagination cursor. Omit for the first page. To fetch the next page, pass the nextCursor value from the previous response unchanged and repeat every other parameter exactly (only limit may change); a cursor used with different parameters is rejected. Keep following nextCursor until it is absent to read every row. Later pages re-read the same report, so a cursor expires with it (about 24 hours).
`--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.

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

Parameters

Name	Type	Required	Description
`account_id`	`string`	Required	Microsoft Advertising account ID (AccountId). Required.minLength: 1
`reason`	`string`	Required	Why this tool call is neededminLength: 1, maxLength: 500

Optional parameters (13)

Name	Type	Required	Description
`customer_id`	`string`	Optional	Customer/manager ID (CustomerId). Required when accessing accounts under a manager hierarchy.minLength: 1
`date_range`	`object`	Optional	Custom date range. Provide either date_range or date_preset, not both.
`date_preset`	`string`	Optional	Predefined date range. One of: Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear. `Today` `Yesterday` `LastSevenDays` `ThisWeek` `LastWeek` `LastFourWeeks` `ThisMonth` `LastMonth` `LastThreeMonths` `LastSixMonths` `ThisYear` `LastYear`
`campaign_ids`	`array`	Optional	Filter to specific campaign IDs (up to 100). Accepts JSON array string or actual array.
`ad_group_ids`	`array`	Optional	Filter to specific ad group IDs (up to 200). Accepts JSON array string or actual array.
`keyword_match_type`	`string`	Optional	Filter to keywords bid on this match type (bid_match_type): Exact, Phrase, or Broad. `Exact` `Phrase` `Broad`
`include_quality_score`	`boolean`	Optional	When true (default), includes QualityScore (1-10) plus three sub-component columns: ExpectedCtr, AdRelevance, and LandingPageExperience. Each sub-component is categorical: AboveAverage, Average, or BelowAverage.
`include_all_conversions`	`boolean`	Optional	When true, includes an additional all_conversions block per row (all_conversions, all_revenue, all_cost_per_conversion, all_roas, view_through_conversions). This captures ALL conversion goals including those not marked "Include in Conversions" (e.g., view-through, non-bidding goals). Note: conversions is the bidding-set count only; all_conversions.all_conversions is every conversion goal — typically much larger for accounts with non-bidding goals.
`breakdown_by_goal`	`boolean`	Optional	When true (default), runs a parallel GoalsAndFunnelsReport and returns goal_breakdown keyed by ad_group_id. Each entry is an array of per-goal rows with all_conversions, all_revenue, view_through_conversions, and assists. IMPORTANT: Because GoalsAndFunnelsReport only scopes down to ad-group level (Bing does not support keyword-level goal breakdown), the breakdown is at ad_group granularity — NOT per keyword. goal_breakdown_granularity will always be "ad_group" for this tool. Each keyword row can look up its parent ad-group's goal breakdown via goal_breakdown[ad_group_id]. Pass false to skip the parallel report when latency matters more than goal context.
`aggregation`	`string`	Optional	Report aggregation period. Daily (default), Weekly, Monthly, or Summary (all dates collapsed). `Daily` `Weekly` `Monthly` `Summary`
`limit`	`integer`	Optional	Page size: rows per page (1–10000, default 15). count is the total across all pages. When more rows remain the response carries nextCursor; pass it back as cursor to get the next page. Large pages can exceed what an MCP client accepts in one response (roughly 60 rows, fewer with include_all_conversions, and breakdown_by_goal adds ~5K characters per ad group on the page); to cover every keyword, follow nextCursor rather than raising limit.min: 1, max: 10000
`cursor`	`string`	Optional	Opaque pagination cursor. Omit for the first page. To fetch the next page, pass the nextCursor value from the previous response unchanged and repeat every other parameter exactly (only limit may change); a cursor used with different parameters is rejected. Keep following nextCursor until it is absent to read every row. Later pages re-read the same report, so a cursor expires with it (about 24 hours).minLength: 1
`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.