get_platform_top_performers

What it does

Parameters

• platform string required

  tiktok or snapchat (Meta has its own reads and actions)

  One of tiktok, snapchat

• ad_account_id string required

  The ad account, from list_ad_accounts with the same platform: a TikTok advertiser id (digits), a Snapchat ad account id (a UUID)

  Matches ^[A-Za-z0-9][A-Za-z0-9-]{0,63}$

• metric string required

  What ranks them: roas, cpa, ctr, spend, purchases, revenue, cpc, cpm, clicks or impressions (cpa, cpc, cpm: the lowest is the best)

  One of spend, revenue, roas, purchases, ctr, clicks, impressions, cpa, cpc, cpm

• level string optional

  Default ad

  One of campaign, adset, ad

• date_preset string optional

  Default last_7d (the 7 days before today, today left out), in the ad account's time zone

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

• since string optional

  YYYY-MM-DD, with until (both included), instead of date_preset

  Matches ^\d{4}-\d{2}-\d{2}$

• until string optional

  YYYY-MM-DD, with since

  Matches ^\d{4}-\d{2}-\d{2}$

• campaign_id string optional

  Only this campaign's

  Matches ^[A-Za-z0-9][A-Za-z0-9-]{0,63}$

• adset_id string optional

  Only this ad group / ad squad's ads

  Matches ^[A-Za-z0-9][A-Za-z0-9-]{0,63}$

• min_spend number optional

  Only those that spent at least this much (account currency); those that spent nothing are always left out

  ≥ 0

• limit integer optional

  How many best and worst, default 10

  1 to 50

Example

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_platform_top_performers",
    "arguments": {
      "platform": "tiktok",
      "ad_account_id": "7000000000000000001",
      "metric": "spend"
    }
  }
}

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 -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_platform_top_performers","arguments":{"platform":"tiktok","ad_account_id":"7000000000000000001","metric":"spend"}}}'

Access and cost

Related tools

TikTok and Snapchat: list_ad_accounts, list_campaigns, list_adsets, list_ads, get_launch_questions and prepare_launch take platform: "tiktok" or "snapchat" (default "meta"); launch and launch_status follow the plan whatever its platform: the same interview, the same recap, the same explicit yes. The tools below read their numbers and change their status and budgets, one platform at a time: money in the ad account's currency, days in its time zone, TikTok and Snapchat never added up.

• get_platform_overview: One TikTok or Snapchat ad account's totals over a period: spend, impressions, clicks, CTR, CPC, CPM, reach, purchases, revenue, ROAS, CPA, add to carts. For Meta: get_account_overview.
• get_platform_performance: One row per campaign, ad set (TikTok ad group, Snapchat ad squad) or ad, with its status, daily budget and metrics, sorted by spend by default. TikTok's Smart+ ads included.
• get_platform_daily_breakdown: Day by day (92 days at most, every day listed) for the ad account or one campaign, ad set or ad, with the period's totals. For Meta: get_daily_breakdown.
• list_targeting: TikTok interests, behaviors and languages, Snapchat interests and countries, with the launch field their ids go in. Meta's targeting: search_targeting.
• list_tiktok_posts: TikTok Spark Ads: the existing posts a launch can run as ads, keeping their likes and comments. source: "account" (default): the video posts of one of the brand's TikTok accounts (the first one, or identity_id from the launch interview), a page at a time; source: "authorized": the posts creators authorized for this ad account. Each post says whether it can run and gives its spark_post for prepare_launch.
• list_tiktok_music: TikTok carousels (image ads run with a music): the music of TikTok's carousel library a launch can use. q: a keyword (e.g. "upbeat"); without one, the music this ad account used. Each gives its music_id for prepare_launch (tiktok.ad_settings.music_id); none given, TikTok picks one for each carousel at the launch.
• list_platform_templates: TikTok and Snapchat: the Quick Bulk Edit templates saved in the Apogee app ("Save as template" in the ad group / ad squad and ad params), per ad account. level: "adgroup": an ad group's (TikTok) or an ad squad's (Snapchat) settings; level: "ad": an ad's (TikTok account, texts, URL, call to action…). prepare_launch uses one as its base: tiktok.adgroup_template_id / tiktok.ad_template_id, snapchat.adsquad_template_id / snapchat.ad_template_id. Saving and deleting templates stay in the app.
• set_platform_status: Prepares pausing or turning on TikTok or Snapchat campaigns, ad sets or ads; execute_action runs it after your OK. TikTok GMV Max and legacy Smart+ campaigns, and the ads TikTok generates inside Smart+ ad groups, are changed in TikTok Ads Manager.
• set_platform_daily_budget: Prepares a new daily budget for a TikTok or Snapchat campaign or ad set, in the ad account's currency; execute_action runs it after your OK. Refused above the safety cap, on a lifetime budget, on an ad set whose campaign holds the budget, and on TikTok Smart+ budgets.