---
title: "Meta paid-ad performance"
method: GET
path: "/meta-ads/ad-performance"
tags: ["Meta Ads"]
---

# Meta paid-ad performance

`GET /meta-ads/ad-performance`

Marketing API performance for the shop's connected ad account over a preset window: account-level totals (impressions, clicks, reach, spend, CTR, CPM, conversions) plus a per-ad table carrying the same metrics alongside each ad's creative — thumbnail, headline, body copy, link, call-to-action, and the branded-content partner's Instagram account for Partnership ads. 

`conversions` is the sum of every entry in Meta's `actions` breakdown, because the insights edge exposes no single conversions field — read it as total attributed actions, not purchases. `spend` and the derived rates are in `currency`, the ad account's own currency, which need not match the shop's TikTok currency. 

This is **paid Meta** data straight from the Marketing API and is unrelated to the rev-share attribution figures at `/meta-ads/campaigns/{campaign_id}/rollups`, which come from Reacher's own ledger — do not add them together. Sub-fetches are best-effort: a failing insights edge yields zeros and an empty ad list rather than an error. Returns 400 when the shop has no ad account linked. Single shop only.

## Query parameters

- `date_preset` string — Meta Marketing API reporting window. One of: last_14d, last_28d, last_30d, last_3d, last_7d, last_90d, last_month, last_quarter, maximum, this_month, this_quarter, today, yesterday.

## Response `200`

Successful Response

- AdPerformanceResponse — Aggregate payload for the Ad Performance tab — exactly the metric set the Meta reviewer asks for on ads_management / ads_read screencasts (Impressions, Conversions, Spend, Clicks, Reach), plus a list of the ads themselves so the surface has both a top-line scoreboard and a drill-down table.
  - `account_id` string, nullable
  - `account_name` string, nullable
  - `currency` string, nullable
  - `date_preset` string
  - `totals` AdPerformanceMetrics — All numeric — defaults to 0 so the FE can render a card without a `value ?? '—'` dance. `conversions` is the sum of all `actions` entries (across action_type) since the bare Marketing API doesn't surface a single "conversions" field — apps must aggregate the action breakdown themselves.
    - `impressions` integer
    - `clicks` integer
    - `reach` integer
    - `spend` number
    - `ctr` number
    - `cpm` number
    - `conversions` integer
  - `ads` AdRow[]
    - `id` string, required
    - `name` string, nullable
    - `status` string, nullable
    - `effective_status` string, nullable
    - `created_time` string, nullable
    - `campaign_id` string, nullable
    - `adset_id` string, nullable
    - `creative_id` string, nullable
    - `thumbnail_url` string, nullable
    - `headline` string, nullable
    - `message` string, nullable
    - `link_url` string, nullable
    - `cta_type` string, nullable
    - `partner_ig_user_id` string, nullable
    - `partner_ig_username` string, nullable
    - `video_id` string, nullable
    - `video_url` string, nullable
    - `impressions` integer
    - `clicks` integer
    - `reach` integer
    - `spend` number
    - `ctr` number
    - `cpm` number
    - `conversions` integer

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/reacherapp/apis/reacher-data-api.md) · [All operations](https://skmtc.dev/reacherapp/apis/reacher-data-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/reacherapp/reacher-data-api/revisions/578c830ce294/schema)