meta_ads_get_performance_report

Get Meta Ads Performance Report

Meta

Description

Full impression-to-conversion funnel report with delivery, engagement, actions, conversions, ROAS, and quality rankings. Supports breakdowns by device (impression_device), demographics (age, gender), geography (country, region, dma), and platform (device_platform, publisher_platform, platform_position). For Advantage+ Shopping Campaigns, supports \

Read-onlyIdempotent

Usage

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "meta_ads_get_performance_report",
    "arguments": {
      "account_id": "act_123",
      "time_range": {
        "since": "2024-01-01",
        "until": "2024-01-31"
      },
      "reason": "Monthly performance review"
    }
  }
}

Parameters

NameTypeRequiredDescription
account_id string Required Meta ad account IDminLength: 1
time_range object Required Required date range {since, until} in YYYY-MM-DD
reason string Required Why this tool call is neededminLength: 1, maxLength: 500
Optional parameters (7)
NameTypeRequiredDescription
time_increment object Optional Time grouping: 1=daily, 7=weekly, or "monthly"
level string Optional Aggregation level (default: account): account, campaign, adset, ad
account campaign adset ad
breakdowns array Optional Dimensions to segment data by. Pass multiple values in a single call to get cross-tabulated rows (e.g. ["age","gender"] → one row per "35-44 / female" segment). Do NOT make separate calls for each dimension. Available: age, gender, country, region, device_platform, publisher_platform, platform_position, impression_device, dma, user_segment_key. Note: `user_segment_key` is the Advantage+ Shopping Campaigns "Audience Segments" breakdown. Returned values: prospecting, engaged, existing, unknown (lowercase). Cross-tabulation with demographic breakdowns like age is rejected by Meta's API — combine with country if needed; use separate calls for demographic splits.
filtering array Optional Filters as [{field, operator, value}]
action_attribution_windows array Optional Attribution windows for action/conversion metrics. Controls which click/view windows are reported. Common: ["7d_click"] for 7-day click only. Default (when omitted): ["7d_click","1d_view"]. Available: 1d_click, 7d_click, 28d_click, 1d_view, 7d_view, 28d_view, 1d_ev, default
limit integer Optional Maximum number of rows per page (default: 100, max: 500)min: 1, max: 500
cursor string Optional Pagination cursor from previous responseminLength: 1

Examples

Account overview

{
  "account_id": "act_123",
  "time_range": {
    "since": "2024-01-01",
    "until": "2024-01-31"
  },
  "reason": "Monthly performance review"
}

hopkin meta performance-report get --account act_123 --time-range [object Object]

Campaign comparison

{
  "account_id": "act_123",
  "time_range": {
    "since": "2024-01-01",
    "until": "2024-01-31"
  },
  "level": "campaign",
  "reason": "Compare campaign performance"
}

hopkin meta performance-report get --account act_123 --time-range [object Object] --level campaign

Daily trend

{
  "account_id": "act_123",
  "time_range": {
    "since": "2024-01-01",
    "until": "2024-01-07"
  },
  "time_increment": 1,
  "reason": "Daily performance trend"
}

hopkin meta performance-report get --account act_123 --time-range [object Object] --time-increment 1

Demographics

{
  "account_id": "act_123",
  "time_range": {
    "since": "2024-01-01",
    "until": "2024-01-31"
  },
  "breakdowns": [
    "age",
    "gender"
  ],
  "reason": "Demographic analysis"
}

hopkin meta performance-report get --account act_123 --time-range [object Object] --breakdowns age,gender

Device breakdown

{
  "account_id": "act_123",
  "date_preset": "last_30d",
  "level": "campaign",
  "breakdowns": [
    "impression_device"
  ],
  "reason": "Device performance analysis"
}

hopkin meta performance-report get --account act_123 --date-preset last_30d --level campaign --breakdowns impression_device

7-day click attribution report

{
  "account_id": "act_123456789",
  "time_range": {
    "since": "2024-01-01",
    "until": "2024-01-31"
  },
  "action_attribution_windows": [
    "7d_click"
  ],
  "reason": "Full-funnel report scoped to 7-day click attribution only"
}

hopkin meta performance-report get --account act_123456789 --time-range [object Object] --action-attribution-windows 7d_click

ASC audience-segment performance report

{
  "account_id": "act_123",
  "time_range": {
    "since": "2024-01-01",
    "until": "2024-01-31"
  },
  "level": "campaign",
  "breakdowns": [
    "user_segment_key"
  ],
  "filtering": [
    {
      "field": "campaign.objective",
      "operator": "EQUAL",
      "value": "OUTCOME_SALES"
    }
  ],
  "reason": "ASC audience segments — full-funnel report split by prospecting vs engaged vs existing vs unknown"
}

hopkin meta performance-report get --account act_123 --time-range [object Object] --level campaign --breakdowns user_segment_key --filtering [object Object]