microsoft_ads_list_ad_groups

List Microsoft Ads Ad Groups

Microsoft

Description

List ad groups across one or more Microsoft Ads campaigns.

Read-onlyOpen-world

Usage

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "microsoft_ads_list_ad_groups",
    "arguments": {
      "account_id": "123456789",
      "campaign_ids": [
        "987654321"
      ],
      "reason": "Show all ad groups for this campaign"
    }
  }
}

Parameters

NameTypeRequiredDescription
account_id string Required Microsoft Advertising account ID (numeric string).minLength: 1
campaign_ids array Required Required. Parent campaign IDs to list ad groups for (1–50). Ad groups are scoped to a campaign in Bing — supply one or more campaign 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 (9)
NameTypeRequiredDescription
customer_id string Optional Customer/manager ID. Required for managed accounts.minLength: 1
ad_group_id string Optional Look up a single ad group by ID. Mutually exclusive with ad_group_ids. Throws if not found. Filters and pagination are ignored when set.minLength: 1
ad_group_ids array Optional Look up multiple ad groups by ID (max 100). Mutually exclusive with ad_group_id. Filters and pagination are ignored when set.
status array Optional Filter by ad group status. One or more of: Active, Paused, Deleted, Expired.
search string Optional Filter ad groups by name (case-insensitive substring match).minLength: 1
limit integer Optional Number of ad groups per page (default: 20, max: 100).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 ad groups in a campaign

{
  "account_id": "123456789",
  "campaign_ids": [
    "987654321"
  ],
  "reason": "Show all ad groups for this campaign"
}

hopkin microsoft ad-groups list --account 123456789 --campaign-ids 987654321

List ad groups across multiple campaigns

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

hopkin microsoft ad-groups list --account 123456789 --campaign-ids 987654321,987654322

Filter by active status

{
  "account_id": "123456789",
  "campaign_ids": [
    "987654321"
  ],
  "status": [
    "Active"
  ],
  "reason": "List only active ad groups"
}

hopkin microsoft ad-groups list --account 123456789 --campaign-ids 987654321 --status Active

Search by name

{
  "account_id": "123456789",
  "campaign_ids": [
    "987654321"
  ],
  "search": "brand",
  "reason": "Find brand-related ad groups"
}

hopkin microsoft ad-groups list --account 123456789 --campaign-ids 987654321 --search brand

Get by ID

{
  "account_id": "123456789",
  "campaign_ids": [
    "987654321"
  ],
  "ad_group_id": "555666777",
  "reason": "Get a specific ad group"
}

hopkin microsoft ad-groups list --account 123456789 --campaign-ids 987654321 --ad-group-id 555666777

Get multiple by ID

{
  "account_id": "123456789",
  "campaign_ids": [
    "987654321"
  ],
  "ad_group_ids": [
    "555666777",
    "888999111"
  ],
  "reason": "Compare two ad groups"
}

hopkin microsoft ad-groups list --account 123456789 --campaign-ids 987654321 --ad-group-ids 555666777,888999111

Via manager account

{
  "account_id": "123456789",
  "campaign_ids": [
    "987654321"
  ],
  "customer_id": "999888777",
  "reason": "List ad groups via agency manager"
}

hopkin microsoft ad-groups list --account 123456789 --campaign-ids 987654321 --customer-id 999888777

Force refresh

{
  "account_id": "123456789",
  "campaign_ids": [
    "987654321"
  ],
  "refresh": true,
  "reason": "Get latest ad group data from API"
}

hopkin microsoft ad-groups list --account 123456789 --campaign-ids 987654321 --refresh true

Paginated

{
  "account_id": "123456789",
  "campaign_ids": [
    "987654321"
  ],
  "limit": 10,
  "cursor": "eyJvZmZzZXQiOjEwfQ==",
  "reason": "Get second page of ad groups"
}

hopkin microsoft ad-groups list --account 123456789 --campaign-ids 987654321 --limit 10 --cursor eyJvZmZzZXQiOjEwfQ==