microsoft_ads_list_campaigns

List Microsoft Ads Campaigns

Microsoft

Description

List campaigns for a Microsoft Advertising account.

Read-onlyOpen-world

Usage

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "microsoft_ads_list_campaigns",
    "arguments": {
      "account_id": "123456789",
      "reason": "Show all campaigns for this account"
    }
  }
}

Parameters

NameTypeRequiredDescription
account_id string Required Microsoft Advertising Account ID (numeric string)minLength: 1, maxLength: 20, pattern: ^\d+$
reason string Required Why this tool call is neededminLength: 1, maxLength: 500
Optional parameters (13)
NameTypeRequiredDescription
customer_id string Optional Customer/manager ID (CustomerId). Required when accessing accounts via an agency manager. Equivalent to Google's login_customer_id.minLength: 1
campaign_id string Optional Look up a single campaign by ID. Mutually exclusive with campaign_ids. Filters and pagination are ignored when set.minLength: 1
campaign_ids array Optional Look up multiple campaigns by ID (max 50). Mutually exclusive with campaign_id. Filters and pagination are ignored when set. Accepts JSON array string or native array.
status array Optional Filter by campaign status. One or more of: Active, Paused, BudgetPaused, Deleted.
campaign_type array Optional Filter by campaign type. Allowed: Search, Shopping, PerformanceMax, Audience.
search string Optional Filter campaigns by name (case-insensitive substring match).minLength: 1
include_policy_issues boolean Optional Default false. When true, also checks the ads and keywords inside each campaign on this page for editorial (policy) problems — Disapproved, ActiveLimited (approved in some markets only) and Inactive (under review) — and attaches them as policyIssues with Microsoft's reasons and appeal status. This is the account-wide disapproval check: combine with status:["Active"] to cover only running campaigns. Live API scan of every ad group on the page — adds roughly 10-30s. Performance Max asset groups are not covered.
include_url_tracking boolean Optional Default false. When true, runs the account-wide URL tracking audit (UTM and click-parameter checks): returns the account-level tracking template, final URL suffix, MSCLKID and UTM auto-tagging settings as urlTrackingScan.account, and attaches urlTracking to each campaign on this page covering every ad group, ad and keyword that sets its OWN tracking template, custom parameters, final URL suffix or (keywords) final URL — anything not listed inherits from its parent. urlTracking.patterns groups those overrides by shape with counts (a parameter value shows as null where it varies between entities), up to 15 patterns across the page; urlTracking.overrides lists the first 15 across the page with exact values. A campaign whose patterns were cut by that limit reports patternsOmitted > 0 — narrow with campaign_ids to see them. Each campaign row already carries its own values. Combine with status:["Active"] to audit only running campaigns. Live API scan of every ad group on the page — adds roughly 10-30s; can be combined with include_policy_issues at no extra scan cost. Performance Max asset groups are not covered.
include_criteria string Optional Campaign targeting detail, attached to each campaign on this page as settings: location targets and exclusions (with bid modifiers), location intent, radius targets, device bid adjustments, ad schedules, age and gender targets. Default "none" (unlike Google): it costs one extra API call per campaign on the page, so it is opt-in. "summary" caps the location and radius lists at 25 entries per campaign and reports the full size as locationTargetsTotalCount / locationExclusionsTotalCount / radiusTargetsTotalCount when it cut one; ad schedules are never capped; use "summary" for a daily settings check across the account (page through with nextCursor; the default page is up to 10 campaigns here, sized for the client, and fewer when campaigns carry many ad schedules — so a short page with a nextCursor is not the end; narrow with campaign_ids or a smaller limit if a page is still too large). "full" returns every entry uncapped and requires campaign_id or campaign_ids (max 10). For a campaign whose languages is null (its ad groups carry the language), settings.adGroupLanguages lists them, at one more call for that campaign. Bid strategy targets and languages are on every row regardless. Campaign-level targeting only: ad-group-level criteria, which can narrow a campaign's targeting, are not included.
none summary full
limit integer Optional Number of campaigns per page (default: 20, max: 100; default up to 10 with include_criteria, fewer when campaigns carry many ad schedules; an explicit limit is honoured as given). Each row carries its own tracking template and custom parameters, so on accounts with long campaign-level parameters (e.g. managed through Search Ads 360) a 100-campaign page can exceed MCP client output limits — keep the default page size and follow nextCursor instead.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 campaigns

{
  "account_id": "123456789",
  "reason": "Show all campaigns for this account"
}

hopkin microsoft campaigns list --account 123456789

Filter by status

{
  "account_id": "123456789",
  "status": [
    "Active"
  ],
  "reason": "List only active campaigns"
}

hopkin microsoft campaigns list --account 123456789 --status Active

Filter by type

{
  "account_id": "123456789",
  "campaign_type": [
    "Search",
    "PerformanceMax"
  ],
  "reason": "List Search and PMax campaigns"
}

hopkin microsoft campaigns list --account 123456789 --campaign-type Search,PerformanceMax

Search by name

{
  "account_id": "123456789",
  "search": "brand",
  "reason": "Find brand campaigns"
}

hopkin microsoft campaigns list --account 123456789 --search brand

Get by ID

{
  "account_id": "123456789",
  "campaign_id": "987654321",
  "reason": "Get specific campaign details"
}

hopkin microsoft campaigns list --account 123456789 --campaign 987654321

Get multiple by ID

{
  "account_id": "123456789",
  "campaign_ids": [
    "111",
    "222",
    "333"
  ],
  "reason": "Compare specific campaigns"
}

hopkin microsoft campaigns list --account 123456789 --campaign-ids 111,222,333

Via manager account

{
  "account_id": "123456789",
  "customer_id": "999888777",
  "reason": "List campaigns via agency manager"
}

hopkin microsoft campaigns list --account 123456789 --customer-id 999888777

Account-wide policy check (active campaigns)

{
  "account_id": "123456789",
  "status": [
    "Active"
  ],
  "include_policy_issues": true,
  "limit": 100,
  "reason": "Daily check for disapproved ads and keywords on running campaigns"
}

hopkin microsoft campaigns list --account 123456789 --status Active --include-policy-issues true --limit 100

Policy issues for one campaign

{
  "account_id": "123456789",
  "campaign_id": "987654321",
  "include_policy_issues": true,
  "reason": "Investigate why this campaign is underdelivering"
}

hopkin microsoft campaigns list --account 123456789 --campaign 987654321 --include-policy-issues true

Daily settings check (bid targets, locations, languages)

{
  "account_id": "123456789",
  "include_criteria": "summary",
  "reason": "Verify no target CPA, location or language changed since yesterday"
}

hopkin microsoft campaigns list --account 123456789 --include-criteria summary

Every location target of named campaigns

{
  "account_id": "123456789",
  "campaign_ids": [
    "111",
    "222"
  ],
  "include_criteria": "full",
  "reason": "List every ZIP code these campaigns target"
}

hopkin microsoft campaigns list --account 123456789 --campaign-ids 111,222 --include-criteria full

Force refresh

{
  "account_id": "123456789",
  "refresh": true,
  "reason": "Get latest campaign data from API"
}

hopkin microsoft campaigns list --account 123456789 --refresh true

Paginated

{
  "account_id": "123456789",
  "limit": 10,
  "cursor": "eyJvZmZzZXQiOjEwfQ==",
  "reason": "Get second page of campaigns"
}

hopkin microsoft campaigns list --account 123456789 --limit 10 --cursor eyJvZmZzZXQiOjEwfQ==