Microsoft Advertising Read
The ACTUAL search queries that triggered your ads (the text surface), with the matched keyword and match type
POST https://api.adspirer.ai/api/v1/tools/get_microsoft_search_terms/execute
Authorization: Bearer sk_live_... — your Adspirer API key (required)Content-Type: application/json (required)Idempotency-Key: <uuid> — recommended for write operations to make retries safeAll tool arguments are wrapped in an arguments object.
| Field | Type | Description |
|---|---|---|
account_id | string optional | Microsoft 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_id | string optional | Alias of account_id (the ad account id, not the manager id). |
start_date | string optional | Window start YYYY-MM-DD (default: 90 days before end_date). |
end_date | string optional | Window end YYYY-MM-DD (default: today). |
query | string optional | Free-text search (case-insensitive substring) over this report's text surface (names/ids and, where present, keyword/query/geo/product/creative text). Empty = all. |
search | string optional | Alias of query. |
sort_by | string optional | Sort field: spend|clicks|impressions|conversions|revenue|roas|cpa|cpc|ctr|conversion_rate|quality_score|impression_share (default spend). default: "spend" |
sort_dir | string optional | 'desc' (default, biggest first) or 'asc'. default: "desc" |
offset | integer optional | Pagination offset (snapped to a page boundary). Paging is capped to protect the account's tool-call quota; narrow with filters instead of deep paging. default: 0 |
limit | integer optional | Rows per page (default 50, 10–200). default: 50 |
min_spend | number optional | Only rows with spend ≥ this (account currency, plain decimal). |
max_spend | number optional | Only rows with spend ≤ this. |
min_clicks | number optional | Only rows with clicks ≥ this. |
min_impressions | number optional | Only rows with impressions ≥ this. |
min_conversions | number optional | Only rows with conversions ≥ this. |
min_roas | number optional | Only rows with ROAS ≥ this. |
max_roas | number optional | Only rows with ROAS ≤ this. |
min_cpa | number optional | Only rows with cost/conversion ≥ this. |
max_cpa | number optional | Only rows with cost/conversion ≤ this. |
zero_conversions | boolean optional | true → only rows with 0 conversions (wasted-spend hunt). |
{
"arguments": {
"account_id": "string",
"customer_id": "string",
"start_date": "string",
"end_date": "string",
"query": "string",
"search": "string"
}
}
{
"success": true,
"data": {
"text": "(tool-specific textual output for get_microsoft_search_terms)",
"quota": {
"used": 42,
"limit": 150,
"tier": "plus",
"period_end": "2026-05-01"
}
},
"tool": "get_microsoft_search_terms"
}
{
"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": "get_microsoft_search_terms"
}
{
"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": "get_microsoft_search_terms",
"quota": {
"used": 150,
"limit": 150,
"tier": "plus",
"period_end": "2026-05-01",
"upgrade_url": "https://adspirer.ai"
}
}
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