microsoft_ads_get_audience_report

Get Microsoft Ads Audience Report

Microsoft

Description

Read-onlyOpen-world

Usage

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "microsoft_ads_get_audience_report",
    "arguments": {}
  }
}

Parameters

NameTypeRequiredDescription
account_id string Required Microsoft Advertising account ID (AccountId). Required.minLength: 1
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 under a manager hierarchy.minLength: 1
date_range object Optional Custom date range. Provide either date_range or date_preset.
date_preset string Optional Predefined date range: Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear.
Today Yesterday LastSevenDays ThisWeek LastWeek LastFourWeeks ThisMonth LastMonth LastThreeMonths LastSixMonths ThisYear LastYear
breakdowns array Optional One or more breakdown dimensions to include as columns. Microsoft Ads serves these across three different report types, so each call must pick breakdowns from one group only: • demographics: AgeGroup, Gender (AgeGenderAudienceReport) • geo: Location (GeographicPerformanceReport) • campaign: Device, DayOfWeek, HourOfDay (CampaignPerformanceReport) Cross-group combinations (e.g. AgeGroup + Device) are rejected — split them into separate calls. DayOfWeek and HourOfDay are mutually-exclusive aggregations and cannot be combined. When breakdowns include DayOfWeek or HourOfDay, the aggregation parameter must be Summary (the breakdown itself becomes the aggregation). Default: ["AgeGroup"].
campaign_ids array Optional Filter to specific campaign IDs (up to 100). Accepts JSON array string or actual array.
campaign_type array Optional Return only rows from campaigns of these types. Options: Search, Shopping, PerformanceMax, Audience. Applied to the report rows before order_by and limit, so the limit counts matching rows only; goal_breakdown covers the matching campaigns. Video is rejected with an error: Microsoft Audience Network video runs in Audience campaigns, so use Audience.
aggregation string Optional Report aggregation period. Summary (default — collapses all dates), Daily, Weekly, Monthly.
Daily Weekly Monthly Summary
limit integer Optional Page size: rows per page (1–10000, default 1000; the geo/Location route defaults to 50 instead when limit is not explicitly set). count is the total across all pages. When more rows remain the response carries nextCursor; pass it back as cursor to get the next page.min: 1, max: 10000
cursor string Optional Opaque pagination cursor. Omit for the first page. To fetch the next page, pass the nextCursor value from the previous response unchanged and repeat every other parameter exactly (only limit may change); a cursor used with different parameters is rejected. Later pages re-read the same report, so a cursor expires with it (about 24 hours).minLength: 1
include_all_conversions boolean Optional When true, adds an all_conversions sub-object to each row containing AllConversionsQualified (all goals, including non-bidding), AllRevenue, ViewThroughConversionsQualified, and derived all_cost_per_conversion / all_roas. Mirrors the google-ads-mcp include_all_conversions opt-in. Default: false. The conversions field always contains bidding-set conversions (ConversionsQualified) only; all_conversions.all_conversions captures every conversion goal including those not marked "Include in Conversions" — typically 2-13× larger.
breakdown_by_goal boolean Optional When true (default), runs a parallel GoalsAndFunnelsReport and attaches goal_breakdown keyed by campaign_id (campaign-scope when campaign_ids filter present, account_id otherwise) to the response. Granularity is campaign-level (Bing does not support demographic/geo-level goal joins). Set to false to skip the parallel call when latency matters more than goal split.
order_by string Optional Sort rows by this metric descending before applying the limit. Default: spend. Options: spend, impressions, clicks, conversions, revenue, ctr. For geo (Location) breakdowns this is especially important: Bing returns rows ordered by location_id, not spend, so without sorting the top-N rows are arbitrary city IDs.
spend impressions clicks conversions revenue ctr
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.