API Reference › Microsoft Advertising › list_microsoft_budgets

list_microsoft_budgets

Microsoft Advertising Read

List the shared budgets in the account's budget library — id, name, amount (plain decimal account currency), budget type and how many campaigns use each

Endpoint

POST https://api.adspirer.ai/api/v1/tools/list_microsoft_budgets/execute

Headers

Description

List the shared budgets in the account's budget library — id, name, amount (plain decimal account currency), budget type and how many campaigns use each. Search by name, filter by type, sort and paginate.

Request body

All tool arguments are wrapped in an arguments object.

FieldTypeDescription
account_idstring optionalMicrosoft Advertising ad account id (numeric AccountId — NOT the 8-character account number shown in the UI). Get it from list_microsoft_accounts. Required when more than one account is connected; may be omitted with exactly one. `customer_id` is accepted as an alias. If the tool replies that several accounts are connected, re-run with this set — that reply is NOT a connection problem.
customer_idstring optionalAlias of account_id (the ad account id, not the manager id).
querystring optionalFree-text search — case-insensitive substring match across name/id and, for ads/keywords, the copy (headlines, descriptions, keyword text). Leave empty for all.
status_filterstring optionalFilter by status, comma-separated (e.g. 'Active' or 'Active,Paused'). 'all' or empty = every status.
type_filterstring optionalFilter by the entity's type field, comma-separated (campaign_type / ad_group_type / ad type / match_type / budget_type depending on the tool). 'all' or empty = every type.
started_afterstring optionalDate filter (YYYY-MM-DD): only entities whose START date is on/after this. Applies to levels that have a start date (campaigns, ad groups); entities with no explicit start date are excluded while a date filter is active.
started_beforestring optionalDate filter (YYYY-MM-DD): only entities whose START date is on/before this.
sort_bystring optionalField to sort by (e.g. name, status, daily_budget, cpc_bid, bid, amount). Any returned field name.
sort_orderstring optional'asc' (default) or 'desc'. default: "asc"
offsetinteger optionalPagination offset — skip this many results (default 0). Use with limit to page through. default: 0
limitinteger optionalMax results per page (default 50). The response reports total, filtered and has_more. default: 50

Example request

{
  "arguments": {
    "account_id": "string",
    "customer_id": "string",
    "query": "string",
    "status_filter": "string",
    "type_filter": "string",
    "started_after": "string"
  }
}

Example responses

200 — Success

{
  "success": true,
  "data": {
    "text": "(tool-specific textual output for list_microsoft_budgets)",
    "quota": {
      "used": 42,
      "limit": 150,
      "tier": "plus",
      "period_end": "2026-05-01"
    }
  },
  "tool": "list_microsoft_budgets"
}

400 — Tool-level error (bad arguments / multi-account selection)

{
  "success": false,
  "error": "You have 25 meta_ads accounts connected. Please specify which account to use by passing the ad_account_id parameter:\n  - Acme Holdings (ad_account_id=\"act_123456789\")\n  - Acme EU (ad_account_id=\"act_987654321\")",
  "is_error": true,
  "tool": "list_microsoft_budgets"
}

402 — Quota exhausted

{
  "success": false,
  "error": "\ud83d\udea8 Monthly limit reached (150/150 tool calls on Plus tier).\nUpgrade to Pro at https://adspirer.ai to keep building.",
  "is_error": true,
  "tool": "list_microsoft_budgets",
  "quota": {
    "used": 150,
    "limit": 150,
    "tier": "plus",
    "period_end": "2026-05-01",
    "upgrade_url": "https://adspirer.ai"
  }
}

Try it live

Interactive: Swagger UI

Machine-readable: OpenAPI 3.1 spec · llms-full.txt

More tools: Microsoft Advertising · All tools

Adspirer REST API — get an API key at adspirer.ai/keys · adspirer.ai