---
title: "Rank ads by performance"
method: GET
path: "/v1/ads/performance"
tags: ["Ad Campaigns"]
---

# Rank ads by performance

`GET /v1/ads/performance`

## Request

- Base URL: `https://zernio.com/api`
- URL: `https://zernio.com/api/v1/ads/performance`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/zernio/apis/zernio-api/docs/v1/ads/performance/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns an ads account's ads ranked by spend, impressions, clicks, results or ROAS over a date range, each with its creative (type, thumbnail, headline, body, link) and campaign.

Use it to see which creatives perform best. `accountId` is sibling-expanded like `/v1/ads/timeline`.

Money is ranked by its raw amount, so pass `adAccountId` when the connection's ad accounts bill in different currencies.

A Meta range older than the imported history answers `202` with `backfillPending: true` and the covered part; repeat the request until it returns 200.

## Query parameters

- `accountId` string, required
- `adAccountId` string
- `fromDate` string, date, required
- `toDate` string, date, required
- `platform` 'facebook' | 'instagram' | 'tiktok' | 'linkedin' | 'pinterest' | 'google' | 'twitter' | 'openai' | 'reddit' | 'microsoft'
- `sortBy` 'spend' | 'impressions' | 'clicks' | 'conversions' | 'roas'
- `limit` integer

## Response `200`

Ads ranked by `sortBy`. Ads with no delivery in the range are left out.

- AdsPerformanceResponse
  - `ads` object[], required
    - `adId` string: Zernio ad ID.
    - `platformAdId` string, nullable
    - `platform` string
    - `name` string
    - `status` string, nullable
    - `campaignName` string, nullable
    - `adSetName` string, nullable
    - `currency` string, nullable: ISO 4217 code of the ad's money metrics.
    - `creative` object
      - `type` 'image' | 'video' | 'carousel' | 'document' | 'text' | 'null', nullable: Same classification as the ad `creativeType`.
      - `thumbnailUrl` string, nullable
      - `headline` string, nullable
      - `body` string, nullable
      - `linkUrl` string, nullable
    - `metrics` object
      - `spend` number: In the ad's currency.
      - `impressions` integer
      - `clicks` integer
      - `ctr` number: Percent.
      - `conversions` number: Results over the range (see AdMetrics.conversions).
      - `costPerConversion` number
      - `purchaseValue` number
      - `roas` number
      - `conversionsByType` object: `conversions` split by what was counted (Meta action_type or Google conversion action name).

## Other responses

- `202`: Meta only. Historical data is incomplete and backfill remains pending.
- `400`: Invalid request
- `401`: Missing or invalid API key. `code` is `missing_credentials` when no Authorization header was sent and `invalid_credentials` when the key is unknown, revoked or expired.
- `403`: Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.
- `404`: The account or requested resource was not found or is not accessible. An account ID may have been disconnected and removed. Read GET /v1/accounts for current account IDs.
- `429`: A limit on your request rate was reached: your plan's API limit, or the team's analytics read cap on a 30-second sliding window. `details.scope` names the capped group (`campaign-analytics`, `ad-analytics`, `ads-listings` or `post-analytics`) and is absent for the API limit.

## Changes

- **2026-11-07** `0398bdc3135e`: 2 warning
  - added the new `text` enum value to the `ads/items/creative/type` response property for the response status `200`
  - added the new `text` enum value to the `allOf[#/components/schemas/AdsPerformanceResponse]/ads/items/creative/type` response property for the response status `202`
- **2026-11-05** `e95a262fd1f4`: 1 info
  - added the non-success response with the status `429`
- **2026-11-03** `e997a9b58205`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/ads/performance/get.md)

---

[API](https://skmtc.dev/zernio/apis/zernio-api.md) - [All operations](https://skmtc.dev/zernio/apis/zernio-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zernio/apis/zernio-api/revisions/17bc9ab1588a?raw)