microsoft_ads_get_insights

Description

Flexible Microsoft Advertising report query. Lets you pick exactly which report type, columns, date range, aggregation, and filters to apply. Use this tool when you need columns or report types not covered by microsoft_ads_get_performance_report. Supported report types: CampaignPerformance, AdGroupPerformance, AdPerformance, KeywordPerformance, SearchQueryPerformance, AudiencePerformance. All columns must be valid for the chosen report_type (validated before submission). DON'T use this for standard breakdowns that have dedicated tools — they pre-select the right report type and columns, so prefer them: • Demographic / geo / device / time-of-day slices (AgeGroup, Gender, Device, Location, DayOfWeek, HourOfDay) → microsoft_ads_get_audience_report • Audience LIST / segment performance (remarketing, in-market, custom, similar) → microsoft_ads_get_audience_segment_report • A single account-wide performance total → microsoft_ads_get_account_summary • Per-campaign/ad-group/ad/keyword performance rows → microsoft_ads_get_performance_report • Search-term analysis → microsoft_ads_get_search_terms Reach for get_insights only when you need columns or a report_type those tools don't cover. IMPORTANT: This tool triggers Microsoft's async report pipeline (submit → poll → download). Expect 5–30 seconds per call. Large date ranges or many columns slow it down. Use date_preset for convenience, or date_range for precise control. PAGING: rows come back one page at a time, sorted Spend highest first when Spend is a requested column. Leave limit unset: each page is then sized so the whole response fits what MCP clients accept (up to ${DEFAULT_REPORT_PAGE_ROWS} rows, ending early at about ${RESPONSE_CHAR_BUDGET.toLocaleString('en-US')} characters, so wide rows give fewer rows per page). To get more rows, follow the cursor rather than raising limit; an explicit limit (max ${MAX_REPORT_PAGE_ROWS}) is exact. count is the total across all pages. While pagination.hasMore is true, call again with exactly the same parameters plus cursor = pagination.nextCursor; repeat until hasMore is false to collect every row. Later pages re-read the same report rather than running a new one (no queue wait, each row exactly once), and omit goal_breakdown, which only the first page carries. campaign_ids filters the rows on CampaignId, which is added to the columns (added_columns) when not requested. For standard campaign/ad group/ad performance metrics, prefer microsoft_ads_get_performance_report which pre-selects optimal columns and is simpler to use.

Usage

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "microsoft_ads_get_insights",
    "arguments": {
      "account_id": "1234567890",
      "report_type": "CampaignPerformance",
      "columns": [
        "CampaignId",
        "CampaignName",
        "CampaignType",
        "TimePeriod",
        "ImpressionSharePercent",
        "ImpressionLostToBudgetPercent",
        "ImpressionLostToRankAggPercent",
        "Impressions",
        "Spend"
      ],
      "date_preset": "LastMonth",
      "aggregation": "Monthly",
      "reason": "Analyze competitive impression share by campaign"
    }
  }
}

hopkin microsoft insights get

{
  "mcpServers": {
    "microsoft-ads": {
      "url": "https://microsoft.mcp.hopkin.ai",
      "transport": "sse"
    }
  }
}

Parameters

Examples

{
  "account_id": "1234567890",
  "report_type": "CampaignPerformance",
  "columns": [
    "CampaignId",
    "CampaignName",
    "CampaignType",
    "TimePeriod",
    "ImpressionSharePercent",
    "ImpressionLostToBudgetPercent",
    "ImpressionLostToRankAggPercent",
    "Impressions",
    "Spend"
  ],
  "date_preset": "LastMonth",
  "aggregation": "Monthly",
  "reason": "Analyze competitive impression share by campaign"
}

{
  "account_id": "1234567890",
  "report_type": "SearchQueryPerformance",
  "columns": [
    "CampaignName",
    "AdGroupName",
    "Keyword",
    "BidMatchType",
    "DeliveredMatchType",
    "SearchQuery",
    "TimePeriod",
    "Impressions",
    "Clicks",
    "Spend",
    "ConversionsQualified",
    "Ctr",
    "AverageCpc"
  ],
  "date_range": {
    "start": "2026-04-01",
    "end": "2026-04-17"
  },
  "aggregation": "Daily",
  "ad_group_ids": [
    "9876543210"
  ],
  "reason": "Identify wasted spend from broad match queries in a specific ad group"
}

{
  "account_id": "1234567890",
  "customer_id": "5555555555",
  "report_type": "AudiencePerformance",
  "columns": [
    "CampaignName",
    "AdGroupName",
    "AudienceId",
    "AudienceName",
    "AudienceType",
    "BidAdjustment",
    "TimePeriod",
    "Impressions",
    "Clicks",
    "Spend",
    "ConversionsQualified",
    "Revenue"
  ],
  "date_preset": "LastThreeMonths",
  "aggregation": "Monthly",
  "reason": "Evaluate audience segment ROI for RLSA bid adjustments"
}

{
  "account_id": "1234567890",
  "report_type": "KeywordPerformance",
  "columns": [
    "CampaignName",
    "AdGroupName",
    "Keyword",
    "BidMatchType",
    "QualityScore",
    "ExpectedCtr",
    "AdRelevance",
    "LandingPageExperience",
    "TimePeriod",
    "Impressions",
    "Clicks",
    "AverageCpc"
  ],
  "date_preset": "LastMonth",
  "aggregation": "Summary",
  "reason": "Identify keywords with low Quality Score for optimization"
}

{
  "account_id": "1234567890",
  "report_type": "AdPerformance",
  "columns": [
    "CampaignName",
    "AdGroupName",
    "AdId",
    "AdTitle",
    "AdType",
    "AdStatus",
    "TimePeriod",
    "Impressions",
    "Clicks",
    "Spend",
    "ConversionsQualified",
    "Ctr",
    "AverageCpc"
  ],
  "date_range": {
    "start": "2026-01-01",
    "end": "2026-03-31"
  },
  "aggregation": "Weekly",
  "campaign_ids": [
    "111111111",
    "222222222"
  ],
  "reason": "A/B test RSA ad copy effectiveness across Q1"
}

Related Tools