meta_ads_get_ad_creative_report

Description

Ad-level performance report with full funnel metrics, including video funnel (ThruPlays, 25/50/75/95/100% completions, avg watch time) for video creatives. All conversion types shown individually. Supports two grouping modes: ad_name (default, aggregates ads sharing the same name with a representative ad_id for preview) and ad_id (one row per ad). The representative ad_id can be passed to meta_ads_preview_ads. Rows come back highest spend first. Rows are compact by default: they leave out the per-type cost arrays (cost_per_action_type, cost_per_conversion, cost_per_thruplay), each of which is spend divided by that type's count. Pass full_detail: true to include them. Creative media (asset_type, asset_url, thumbnail_url) is listed once per ad under assets, keyed by each row's ad_id. Each response is one page of at most 50,000 characters, or limit rows if set. When more rows remain it returns nextCursor: pass it as cursor to get the next page, and repeat until nextCursor is absent to walk every row, compact or full detail. Reads up to 2,000 ad-level rows from Meta. truncated is true whenever a response does not hold every row, and truncation gives the reasons, total_rows, returned_rows, remaining_rows and remaining_spend. The reasons are response_size or limit (more pages remain), row_limit (Meta had more rows than the tool reads; no cursor reaches them, unread_spend gives their approximate spend, and ad_name totals may be low, so narrow by campaign, ad set or ad, shorten time_range, or drop time_increment or breakdowns) and report_changed (live numbers moved rows across a page boundary between calls, so rows may be missing or repeated across pages; call again without cursor for a consistent set). A call without cursor always reads the report fresh from Meta; cursor pages served by the same server instance reuse that read for up to 15 minutes, and a page served elsewhere reads Meta again (report_changed flags any rows that moved).

Usage

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "meta_ads_get_ad_creative_report",
    "arguments": {
      "account_id": "act_123",
      "time_range": {
        "since": "2024-01-01",
        "until": "2024-01-31"
      },
      "reason": "Review individual ad performance"
    }
  }
}

hopkin meta ad-creative-report get

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

Parameters

Examples

{
  "account_id": "act_123",
  "time_range": {
    "since": "2024-01-01",
    "until": "2024-01-31"
  },
  "reason": "Review individual ad performance"
}

{
  "account_id": "act_123",
  "time_range": {
    "since": "2024-01-01",
    "until": "2024-01-31"
  },
  "level": "ad_name",
  "reason": "Compare creative variants running across multiple ad sets"
}

{
  "account_id": "act_123",
  "time_range": {
    "since": "2024-01-01",
    "until": "2024-01-31"
  },
  "level": "ad_name",
  "filtering": [
    {
      "field": "campaign.id",
      "operator": "IN",
      "value": [
        "111111111"
      ]
    }
  ],
  "reason": "Creative performance within a specific campaign"
}

{
  "account_id": "act_123",
  "time_range": {
    "since": "2024-01-01",
    "until": "2024-01-31"
  },
  "level": "ad_name",
  "breakdowns": [
    "age",
    "gender"
  ],
  "reason": "Understand which creatives perform best per demographic"
}

{
  "account_id": "act_123",
  "time_range": {
    "since": "2024-01-01",
    "until": "2024-01-31"
  },
  "level": "ad_name",
  "full_detail": true,
  "cursor": "<nextCursor from the previous response>",
  "reason": "Walk every creative with per-type costs, one page at a time"
}

{
  "account_id": "act_123",
  "time_range": {
    "since": "2024-01-01",
    "until": "2024-01-31"
  },
  "level": "ad_name",
  "reason": "Compare ThruPlay performance across Video Views campaign creatives"
}

Related Tools