microsoft_ads_get_search_terms

Get Microsoft Ads Search Terms

Microsoft

Description

Read-onlyOpen-world

Usage

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "microsoft_ads_get_search_terms",
    "arguments": {
      "account_id": "123456789",
      "date_range": {
        "start": "2026-03-18",
        "end": "2026-04-17"
      },
      "reason": "Analyze search query performance"
    }
  }
}

Parameters

NameTypeRequiredDescription
account_id string Required Microsoft Advertising account ID (AccountId)minLength: 1
date_range object Required Date range for the report. Required.
reason string Required Why this tool call is neededminLength: 1, maxLength: 500
Optional parameters (6)
NameTypeRequiredDescription
customer_id string Optional Customer/manager ID (CustomerId). Required for agency-managed accounts.minLength: 1
campaign_ids array Optional Filter to specific campaign IDs (max 100). Omit to include all campaigns.
limit integer Optional Page size: search terms per response (1-10000, default 50). Rows are sorted by Impressions descending, so the first page is the top N. `count` in the response is the total across all pages; when `nextCursor` is present, more rows remain. Large pages can exceed what an MCP client accepts in one response (roughly 100 rows, fewer with include_all_conversions); to cover every term, follow nextCursor rather than raising limit.min: 1, max: 10000
cursor string Optional Opaque cursor for the next page: pass the `nextCursor` value from the previous response unchanged, together with the same parameters as that call (only limit may change). Omit for the first page. Cursors expire after about 24 hours.minLength: 1
include_all_conversions boolean Optional When true, adds the AllConversionsQualified and AllRevenue columns to the report and surfaces them as an all_conversions sub-object on each row. This captures ALL conversion goals including those not marked "Include in Conversions" (e.g. cross-device, non-bidding goals). Microsoft's search term report has no view-through conversion column, so there is no view-through count here. The base Conversions field always reflects ConversionsQualified (bidding-set only). Note: breakdown_by_goal is not available on this tool because Bing's search-term report cannot join GoalsAndFunnelsReport at the search-term level (spec §9.3).
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

Last 30 days, all campaigns

{
  "account_id": "123456789",
  "date_range": {
    "start": "2026-03-18",
    "end": "2026-04-17"
  },
  "reason": "Analyze search query performance"
}

hopkin microsoft search-terms get --account 123456789 --date-range [object Object]

Next page of the same report

{
  "account_id": "123456789",
  "date_range": {
    "start": "2026-03-18",
    "end": "2026-04-17"
  },
  "cursor": "<nextCursor from the previous response>",
  "reason": "Continue through every search term for the wasted-spend review"
}

hopkin microsoft search-terms get --account 123456789 --date-range [object Object] --cursor <nextCursor from the previous response>

Specific campaign, top 100

{
  "account_id": "123456789",
  "date_range": {
    "start": "2026-04-01",
    "end": "2026-04-17"
  },
  "campaign_ids": [
    "987654321"
  ],
  "limit": 100,
  "reason": "Top 100 search terms for brand campaign this month"
}

hopkin microsoft search-terms get --account 123456789 --date-range [object Object] --campaign-ids 987654321 --limit 100

Multi-campaign filter

{
  "account_id": "123456789",
  "date_range": {
    "start": "2026-04-01",
    "end": "2026-04-17"
  },
  "campaign_ids": [
    "111111",
    "222222",
    "333333"
  ],
  "reason": "Search terms across three key campaigns"
}

hopkin microsoft search-terms get --account 123456789 --date-range [object Object] --campaign-ids 111111,222222,333333

Top 50 for quick overview

{
  "account_id": "123456789",
  "date_range": {
    "start": "2026-04-10",
    "end": "2026-04-17"
  },
  "limit": 50,
  "reason": "Quick top 50 search terms overview for the last week"
}

hopkin microsoft search-terms get --account 123456789 --date-range [object Object] --limit 50

Full month with managed account

{
  "account_id": "123456789",
  "customer_id": "555666777",
  "date_range": {
    "start": "2026-03-01",
    "end": "2026-03-31"
  },
  "reason": "March search term performance for agency client"
}

hopkin microsoft search-terms get --account 123456789 --customer-id 555666777 --date-range [object Object]

Include all-conversions data (non-bidding goals)

{
  "account_id": "123456789",
  "date_range": {
    "start": "2026-04-01",
    "end": "2026-04-30"
  },
  "include_all_conversions": true,
  "reason": "Get full conversion picture including non-bidding goals for search terms"
}

hopkin microsoft search-terms get --account 123456789 --date-range [object Object] --include-all-conversions true