---
title: "List ad-account ads by KPI"
method: GET
path: "/open/v1/ad-accounts/{account_id}/ads"
tags: ["Ad Accounts"]
---

# List ad-account ads by KPI

`GET /open/v1/ad-accounts/{account_id}/ads`

List the account's own ads with per-ad metrics, sorted by the chosen KPI and capped at `limit` rows. The ad platform applies the sort + limit server-side, so this stays cheap regardless of total ad count.

Each item carries a thumbnail and the same metric bundle as `/summary`. Use the returned `platform_ad_id` with `GET /open/v1/ad-accounts/{account_id}/ads/{platform_ad_id}` to drill into a single ad's creative + text copy.

**Timeout / page-size guidance**: the underlying Marketing-API insights call scales linearly with the requested page size; high-volume ad accounts can exceed the upstream timeout at larger limits and return `code=50001`. The default is `limit=10` and the validated range is 1–50, but `limit > 20` is risky on busy accounts. The endpoint retries once with a halved limit on upstream failure, but if that still fails, prefer **smaller page sizes** (e.g. `limit=5`) and call the endpoint multiple times with different `sort_by`/`sort_order` combinations to enumerate the ads you need rather than asking for one large page.

Returns: `code=0` success; `code=40001` invalid query / path parameters or workspace context missing; `code=40401` when the account does not exist or belongs to a different workspace; `code=50001` when the upstream platform API is unavailable (including after the internal shrink-retry exhausts).

## Path parameters

- `account_id` string, required — Internal Atria ad-account id (UUID; dashed or 32-char hex both parse). Obtain it from `GET /open/v1/ad-accounts` (`items[].id`).

## Query parameters

- `period` 'last_7d' | 'last_14d' | 'last_30d' — An enumeration.
- `sort_by` 'spend' | 'impressions' | 'ctr' | 'cpm' | 'conversions' | 'roas' — An enumeration.
- `sort_order` 'desc' | 'asc' — An enumeration.
- `limit` integer — Max rows to return (1-50). Defaults to 10. The upstream Marketing-API insights call scales linearly with page size and times out on high-volume accounts, so smaller pages are strongly preferred; the endpoint retries once with a halved limit on upstream timeout. Callers passing `limit > 10` should expect occasional `code=50001` and either retry with a smaller limit or accept a degraded result.

## Response `200`

Successful Response

- OpenOwnAdListResponse — Envelope for all open API responses. code=0 means success.
  - `code` integer
  - `message` string
  - `data` OpenOwnAdListData
    - `items` OpenOwnAdListItem[]
      - `platform_ad_id` string, required — Platform-native ad id (Meta Marketing API `ad_id`, TikTok Marketing API `ad_id`). Use this on `GET /open/v1/ad-accounts/{account_id}/ads/{platform_ad_id}`. Note: this is **not** the Atria-library `ad_id` from `/open/v1/ad-library/*` — different namespace.
      - `ad_name` string — Internal ad name set by the advertiser (e.g. naming convention).
      - `status` string — Ad status from the platform: `ACTIVE` / `PAUSED` / `DISAPPROVED` / etc.
      - `asset_format` string — Creative asset format: `IMAGE` / `VIDEO` / `CAROUSEL` / `DCO`.
      - `thumbnail_url` string — CDN thumbnail / poster URL for at-a-glance preview.
      - `metrics` OpenAdMetrics, required — Performance metrics over the requested date window. Shared by `OpenAccountSummary`, `OpenOwnAdListItem`, and `OpenOwnAd`. All numeric fields are denominated in the ad-account's currency (see the enclosing response's `currency` field).
        - `spend` number, required — Total spend in the account's currency.
        - `impressions` integer, required — Total impressions.
        - `clicks` integer, required — Total clicks (link clicks where applicable).
        - `ctr` number — Click-through rate (clicks / impressions). Null when impressions=0.
        - `cpm` number — Cost per 1000 impressions (spend / impressions × 1000). Null when impressions=0.
        - `cpc` number — Cost per click (spend / clicks). Null when clicks=0.
        - `conversions` integer — Number of conversions. Facebook: `omni_purchase` action count. TikTok: advertiser-defined conversion count. Null when the account has not configured conversion tracking.
        - `cost_per_conversion` number — Spend / conversions. Null when conversions is null or 0.
        - `roas` number — Return on ad spend (purchase value / spend). Null when the account has no purchase-value tracking, or when spend=0.
    - `count` integer, required — Number of items returned (`== len(items)`).
    - `period` 'last_7d' | 'last_14d' | 'last_30d', required — An enumeration.
    - `date_start` string, required
    - `date_stop` string, required
    - `sort_by` 'spend' | 'impressions' | 'ctr' | 'cpm' | 'conversions' | 'roas', required — An enumeration.
    - `sort_order` 'desc' | 'asc', required — An enumeration.

## Other responses

- `400` — Invalid request — a query parameter, path parameter, or body field failed validation.

---

[API](https://skmtc.net/tryatria/apis/atria-open-api.md) · [All operations](https://skmtc.net/tryatria/apis/atria-open-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tryatria/atria-open-api/revisions/548d57b611ea/schema)