`microsoft_ads_list_keywords`

List Microsoft Ads Keywords

Microsoft

Description

Read-onlyOpen-world

Usage

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "microsoft_ads_list_keywords",
    "arguments": {
      "account_id": "123456789",
      "ad_group_id": "987654321",
      "reason": "Review keywords and quality scores"
    }
  }
}

hopkin microsoft keywords list

Flag	Type	Required	Description
`--account`	`string`	Required	Microsoft Advertising account ID (AccountId)
`--customer-id`	`string`	Optional	Customer/manager ID (CustomerId). Required for agency-managed accounts.
`--ad-group-id`	`string`	Required	Ad group ID to list keywords for. Required — API is scoped per ad group.
`--status`	`array`	Optional	Filter by keyword status: Active, Paused, Deleted
`--match-type`	`string`	Optional	Filter by match type: Exact, Phrase, Broad
`--editorial-status`	`array`	Optional	Filter by editorial (policy) review status: Disapproved (failed review), ActiveLimited (approved in some markets only), Inactive (under review), Active (approved). Always answered from a live API call, never from cache.
`--include-policy-issues`	`boolean`	Optional	Default false. When true, attaches the editorial reasons and appeal status for every returned keyword that is NOT editorially Active — what Microsoft objected to and whether it can be appealed. Costs one extra API call and always fetches live data.
`--limit`	`integer`	Optional	Maximum number of keywords to return (1-1000, default 50)
`--cursor`	`string`	Optional	Opaque cursor from the previous response's nextCursor. Pass it with otherwise identical parameters to get the next page; a cursor reused with different filters is rejected. Omit for the first page.
`--refresh`	`boolean`	Optional	Force a live fetch from the Microsoft Ads API, bypassing the local cache. Defaults to false (cache-first — the normal, faster path). Set to true whenever the user asks for fresh / latest / real-time / up-to-date data, or explicitly says they do NOT want cached / stale data. If the user does not care about freshness, leave it 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.

{
  "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)minLength: 1
`ad_group_id`	`string`	Required	Ad group ID to list keywords for. Required — API is scoped per ad group.minLength: 1
`reason`	`string`	Required	Why this tool call is neededminLength: 1, maxLength: 500

Optional parameters (9)

Name	Type	Required	Description
`customer_id`	`string`	Optional	Customer/manager ID (CustomerId). Required for agency-managed accounts.minLength: 1
`status`	`array`	Optional	Filter by keyword status: Active, Paused, Deleted
`match_type`	`string`	Optional	Filter by match type: Exact, Phrase, Broad `Exact` `Phrase` `Broad`
`editorial_status`	`array`	Optional	Filter by editorial (policy) review status: Disapproved (failed review), ActiveLimited (approved in some markets only), Inactive (under review), Active (approved). Always answered from a live API call, never from cache.
`include_policy_issues`	`boolean`	Optional	Default false. When true, attaches the editorial reasons and appeal status for every returned keyword that is NOT editorially Active — what Microsoft objected to and whether it can be appealed. Costs one extra API call and always fetches live data.
`limit`	`integer`	Optional	Maximum number of keywords to return (1-1000, default 50)min: 1, max: 1000
`cursor`	`string`	Optional	Opaque cursor from the previous response's nextCursor. Pass it with otherwise identical parameters to get the next page; a cursor reused with different filters is rejected. Omit for the first page.minLength: 1
`refresh`	`boolean`	Optional	Force a live fetch from the Microsoft Ads API, bypassing the local cache. Defaults to false (cache-first — the normal, faster path). Set to true whenever the user asks for fresh / latest / real-time / up-to-date data, or explicitly says they do NOT want cached / stale data. If the user does not care about freshness, leave it 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

List all keywords in ad group

{
  "account_id": "123456789",
  "ad_group_id": "987654321",
  "reason": "Review keywords and quality scores"
}

hopkin microsoft keywords list --account 123456789 --ad-group-id 987654321

Active keywords only

{
  "account_id": "123456789",
  "ad_group_id": "987654321",
  "status": [
    "Active"
  ],
  "reason": "List active keywords"
}

hopkin microsoft keywords list --account 123456789 --ad-group-id 987654321 --status Active

Exact match only

{
  "account_id": "123456789",
  "ad_group_id": "987654321",
  "match_type": "Exact",
  "reason": "Review exact match keywords"
}

hopkin microsoft keywords list --account 123456789 --ad-group-id 987654321 --match-type Exact

Large ad group paginated

{
  "account_id": "123456789",
  "ad_group_id": "987654321",
  "limit": 50,
  "reason": "Get first 50 keywords"
}

hopkin microsoft keywords list --account 123456789 --ad-group-id 987654321 --limit 50

Disapproved keywords in this ad group

{
  "account_id": "123456789",
  "ad_group_id": "987654321",
  "editorial_status": [
    "Disapproved"
  ],
  "reason": "Check which keywords are blocked by editorial review"
}

hopkin microsoft keywords list --account 123456789 --ad-group-id 987654321 --editorial-status Disapproved

Disapproved keywords with reasons

{
  "account_id": "123456789",
  "ad_group_id": "987654321",
  "editorial_status": [
    "Disapproved"
  ],
  "include_policy_issues": true,
  "reason": "Find out why these keywords were disapproved and whether we can appeal"
}

hopkin microsoft keywords list --account 123456789 --ad-group-id 987654321 --editorial-status Disapproved --include-policy-issues true

Force refresh from the API

{
  "account_id": "123456789",
  "ad_group_id": "987654321",
  "refresh": true,
  "reason": "Get the latest keyword state after bulk edits"
}

hopkin microsoft keywords list --account 123456789 --ad-group-id 987654321 --refresh true