microsoft_ads_list_ads

List Microsoft Ads

Microsoft

Description

Read-onlyOpen-world

Usage

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "microsoft_ads_list_ads",
    "arguments": {
      "account_id": "123456789",
      "ad_group_ids": [
        "987654321"
      ],
      "reason": "List all ads for review"
    }
  }
}

Parameters

NameTypeRequiredDescription
account_id string Required Microsoft Advertising account ID (AccountId)minLength: 1
ad_group_ids array Required Required. Parent ad group IDs to list ads for (1–50). Ads are scoped to an ad group in Bing — supply one or more ad_group_ids whether listing or looking up by ID. Accepts JSON array string or native array.
reason string Required Why this tool call is neededminLength: 1, maxLength: 500
Optional parameters (11)
NameTypeRequiredDescription
customer_id string Optional Customer/manager ID (CustomerId). Required when accessing accounts through an agency/manager relationship.minLength: 1
ad_id string Optional Look up a single ad by ID. Mutually exclusive with ad_ids. Throws if not found. Filters and pagination are ignored when set.minLength: 1
ad_ids array Optional Look up multiple ads by ID (1–50). Mutually exclusive with ad_id. Partial misses are silently dropped. Filters and pagination are ignored when set.
ad_types array Optional Filter by ad type: ResponsiveSearch, ExpandedText, Responsive, DynamicSearch, Product (Shopping). Defaults to all five. Ignored when ad_id/ad_ids is set.
status array Optional Filter by ad status: Active, Paused, Deleted. Ignored when ad_id/ad_ids is set.
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. Ignored when ad_id/ad_ids is set.
include_policy_issues boolean Optional Default false. When true, attaches the editorial reasons and appeal status for every returned ad 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 ads to return (1-100, default 20)min: 1, max: 100
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 ads in an ad group

{
  "account_id": "123456789",
  "ad_group_ids": [
    "987654321"
  ],
  "reason": "List all ads for review"
}

hopkin microsoft ads list --account 123456789 --ad-group-ids 987654321

List ads across multiple ad groups

{
  "account_id": "123456789",
  "ad_group_ids": [
    "987654321",
    "987654322"
  ],
  "reason": "Compare ads across two ad groups"
}

hopkin microsoft ads list --account 123456789 --ad-group-ids 987654321,987654322

Filter by RSA type only

{
  "account_id": "123456789",
  "ad_group_ids": [
    "987654321"
  ],
  "ad_types": [
    "ResponsiveSearch"
  ],
  "reason": "List only responsive search ads"
}

hopkin microsoft ads list --account 123456789 --ad-group-ids 987654321 --ad-types ResponsiveSearch

Filter by active status

{
  "account_id": "123456789",
  "ad_group_ids": [
    "987654321"
  ],
  "status": [
    "Active"
  ],
  "reason": "List active ads"
}

hopkin microsoft ads list --account 123456789 --ad-group-ids 987654321 --status Active

Get a single ad by ID

{
  "account_id": "123456789",
  "ad_group_ids": [
    "987654321"
  ],
  "ad_id": "111222333",
  "reason": "Get full creative for this ad"
}

hopkin microsoft ads list --account 123456789 --ad-group-ids 987654321 --ad 111222333

Get multiple ads by ID

{
  "account_id": "123456789",
  "ad_group_ids": [
    "987654321"
  ],
  "ad_ids": [
    "111222333",
    "444555666"
  ],
  "reason": "Compare two ads side-by-side"
}

hopkin microsoft ads list --account 123456789 --ad-group-ids 987654321 --ad-ids 111222333,444555666

Disapproved ads only

{
  "account_id": "123456789",
  "ad_group_ids": [
    "987654321"
  ],
  "editorial_status": [
    "Disapproved"
  ],
  "reason": "Find ads blocked by editorial review in this ad group"
}

hopkin microsoft ads list --account 123456789 --ad-group-ids 987654321 --editorial-status Disapproved

Disapproved ads with reasons

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

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

Force refresh

{
  "account_id": "123456789",
  "ad_group_ids": [
    "987654321"
  ],
  "refresh": true,
  "reason": "Get latest ad data"
}

hopkin microsoft ads list --account 123456789 --ad-group-ids 987654321 --refresh true

Paginate

{
  "account_id": "123456789",
  "ad_group_ids": [
    "987654321"
  ],
  "limit": 10,
  "cursor": "eyJvZmZzZXQiOjEwfQ",
  "reason": "Get next page of ads"
}

hopkin microsoft ads list --account 123456789 --ad-group-ids 987654321 --limit 10 --cursor eyJvZmZzZXQiOjEwfQ