Get insights

What it does

Request

GET /ad-accounts/{acc}/insights on https://api.apogee.ad/api/v1.

Path parameters

• acc string path required

  Ad account id: Meta act_…, a TikTok advertiser id or a Snapchat ad account id (GET /ad-accounts?platform=…)

  Matches ^(act_\d{1,32}|[A-Za-z0-9][A-Za-z0-9-]{0,63})$

Query parameters

• limit integer query optional

  Page size

  Default 50

  1 to 200

• cursor string query optional

  next_cursor of the previous page

• platform string query optional

  meta (default), tiktok or snapchat

  One of meta, tiktok, snapchat

• level string query optional

  Default account

  One of account, campaign, adset, ad

• date_preset string query optional

  Default last_7d

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

• since string query optional

  TikTok / Snapchat: YYYY-MM-DD, with until (both included), instead of date_preset

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

• until string query optional

  TikTok / Snapchat: YYYY-MM-DD, with since

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

• breakdown string query optional

  TikTok / Snapchat: daily only

  One of daily, placement, age_gender, device

• campaign_id string query optional

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

• adset_id string query optional

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

• ad_id string query optional

  TikTok / Snapchat, breakdown daily: one ad

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

• status string query optional

  Meta: level campaign only; TikTok / Snapchat: any level

  One of active, paused

• sort string query optional

  TikTok / Snapchat levels: the metric the rows are sorted by

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

• min_spend string query optional

  TikTok / Snapchat levels: only rows that spent at least this much

  Matches ^\d{1,9}(\.\d{1,2})?$

Headers

• Authorization string header required

  Bearer apk_…: an API key with the scope of this route.

Response

200. A page of results: pass next_cursor as cursor for the next one, limit from 1 to 200 (default 50).

• data array of objects
  Fields of each item (18)

  • level string

    One of account, campaign, adset, ad, daily, placement, age_gender, device

  • metrics object
    Fields (14)

    • spend number or null
    • impressions number or null
    • clicks number or null
    • ctr number or null
    • cpc number or null
    • cpm number or null
    • reach number or null
    • frequency number or null
    • purchases number or null
    • revenue number or null
    • roas number or null
    • cpa number or null
    • add_to_cart number or null
    • cost_per_atc number or null
  • date_preset string or null
  • since string or null
  • until string or null
  • currency string or null
  • campaign_id string or null
  • adset_id string or null
  • daily_budget number or null
  • id string or null
  • name string or null
  • status string or null
  • date string or null
  • platform string or null
  • position string or null
  • age string or null
  • gender string or null
  • device string or null
• has_more boolean
• next_cursor string or null

Every answer carries X-Request-Id (give it to support), Apogee-Version: 2026-10-06, and the RateLimit and RateLimit-Policy headers.

Errors

Errors are application/problem+json with a stable code to switch on (all the codes).

Example

With your key in APOGEE_API_KEY (create one):

curl 'https://api.apogee.ad/api/v1/ad-accounts/act_1234567890/insights' \
  -H "Authorization: Bearer $APOGEE_API_KEY"

{
  "data": [
    {
      "level": "account",
      "date_preset": "last_7d",
      "since": "2026-10-01",
      "until": "2026-10-21",
      "currency": "EUR",
      "campaign_id": "120200000000000001",
      "adset_id": "120200000000000002",
      "daily_budget": 50,
      "id": "120200000000000001",
      "name": "Nordlicht | Spring launch",
      "status": "ACTIVE",
      "date": "2026-10-21",
      "platform": "meta",
      "position": "120200000000000001",
      "age": "120200000000000001",
      "gender": "120200000000000001",
      "device": "120200000000000001",
      "metrics": {
        "spend": 125.4,
        "impressions": 18250,
        "clicks": 412,
        "ctr": 2.26,
        "cpc": 0.3,
        "cpm": 6.87,
        "reach": 15100,
        "frequency": 1.21,
        "purchases": 9,
        "revenue": 612.5,
        "roas": 4.88,
        "cpa": 13.93,
        "add_to_cart": 31,
        "cost_per_atc": 4.05
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Access and cost

In the MCP

An AI assistant does the same with these tools of the MCP server:

• 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_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_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.