MCP tool · Performance

`get_video_metrics`

Hook rate, hold rate, completion and ThruPlay per video ad.

Read only Scope: read Pro and Scale plans Credits: Free*

What it does

Get creative-level video performance: Hook Rate (3s views / impressions, >25% strong, <15% weak), Hold Rate (p25 watched / 3s views, >70% strong, <50% weak), Completion Rate (p100 / impressions, >25% strong), ThruPlay Rate, quartile retention, cost per 3s view, cost per ThruPlay. Use this for creative strategist analysis: diagnosing weak hooks, retention issues, winning ad breakdowns. Accepts ad_ids (preferred) OR adset_id OR campaign_id.

Parameters

ad_account_id string required

Meta ad account id (act_…), from list_ad_accounts

Matches ^(act_)?\d{1,32}$
ad_ids array of strings optional

Array of Meta ad IDs (preferred — gives per-ad metrics)
adset_id string optional

Ad set ID (aggregate metrics across all ads in the ad set)
campaign_id string optional

Campaign ID (aggregate across all ads in the campaign)
date_preset string optional

Date range (default last_14d)

One of today, yesterday, last_7d, last_14d, last_30d, last_90d, this_month, last_month

Example

Your assistant calls it for you when you ask in your own words. What it sends (MCP tools/call, JSON-RPC 2.0):

tools/call

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

The same call over HTTP with an API key, for an MCP client of your own (an assistant that signs in sends its OAuth token instead):

curl

curl -X POST https://app.apogee.ad/mcp \
  -H "Authorization: Bearer $APOGEE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_video_metrics","arguments":{"ad_account_id":"act_1234567890"}}}'

Access and cost

Plans	Pro and Scale.
Scope	`read`: a connection or an API key without it does not see this tool (scopes).
Effect	Reads only: nothing is changed, in Apogee or on the ad account.
Credits	Free up to the daily free reads (5,000 a day on Pro, 10,000 on Scale), then 1 credit per read. A call that fails costs nothing (credits).
Rate limit	600 MCP requests per 15 minutes on Pro, 1,200 on Scale (rate limits).
Daily cap	Counts 1 unit toward the 2,000 units one API key or assistant connection can use in 24 hours.

Performance: The same reads as Apogee's Autopilot, with the same numbers as the app. Ad names follow your naming convention: ask per concept or per hook.

get_account_overview: Spend, impressions, clicks, CTR, CPC, ROAS and conversions of the ad account for a period.
get_campaigns: The campaigns with their budget, spend and results.
get_adsets: The ad sets with their targeting, budget and metrics.
get_ads: The ads with their creative and metrics.
get_top_performers: The best and the worst campaigns, ad sets or ads by ROAS, CPA, CTR or spend: what to scale, what to cut.
get_daily_breakdown: Spend, ROAS, CPA and add to carts day by day.
get_ad_performance_by_placement: Results by placement (Feed, Stories, Reels…).
get_ad_performance_by_age_gender: Results by age and gender.
get_ad_performance_by_device: Results by device.
get_creative_fatigue_metrics: Frequency, CTR trend and CPC over time; flags tired creatives.
get_ad_creatives: The images, videos and texts of the ads of an ad set or a campaign.
get_audience_insights: The targeting and estimated audience size of ad sets.
get_account_spend_limit: The account's spend cap, amount spent and balance.
get_campaign_budget_optimization: Whether a campaign uses a campaign budget (CBO), and that budget.

What it does

Parameters

Example

Access and cost

Related tools