> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Creatives list

> See every creative an advertiser runs on Meta in one list: whether each is running, in which campaigns, how its ads are doing, and what you can do next.

The creatives list shows, in one read, which of an advertiser's creatives are
running, in which campaigns, and how each one is doing. It lists the
creatives in the advertiser's Creative Library and the creatives running in
its Meta campaigns that are not in the Library yet, such as ads made in Meta
Ads Manager. Each creative carries its ads, its delivery over the last few
days and the actions that apply to it.

It covers Meta campaigns: campaigns you bought through Apostra and campaigns
you connected from your own ad account. It is available to Buyer accounts.

## Read the list

Call `search` with `kind: "creative"`, `include: ["delivery"]` and the
advertiser:

```json theme={null}
{
  "kind": "creative",
  "include": ["delivery"],
  "filter": { "advertiserId": "17002", "deliveryDays": 7 }
}
```

Send `filter.campaignId` instead of `filter.advertiserId` to list only the
creatives of one campaign and that campaign's ads.

| Filter | What it does |
| - | - |
| `deliveryDays` | The window: the last 1 to 30 complete days, in each Meta ad account's timezone. Default 7. |
| `listState` | One tab of the list: `running`, `not_running` (in the Library and not running) or `not_in_library` (a Meta creative not in the Library, running or not). Omit it for every creative. |

The list takes no `query` and no other creative filter. `limit` is 1 to 100,
default 25.

Without `include: ["delivery"]`, `search` with `kind: "creative"` lists your
Library creatives as before, with no delivery.

## What comes back

Each result is one creative. A creative in the Library has every field the
creative search returns, plus:

| Field | Meaning |
| - | - |
| `inLibrary` | `true` for a Creative Library creative, `false` for a Meta creative that is not in the Library. |
| `platformCreativeId` | The Meta creative its top ad runs, or `null` when it has no ad. |
| `runState` | `running`, `paused`, `ready` or `ended`. See [Run states](https://docs.apostra.com/v3/creatives-list.md#run-states). |
| `ads` | Its ads: every ad that delivered in the window or has not ended, running ads first, at most 20. |
| `adsTotal` | How many ads it has, present when there are more than 20. |
| `delivery` | The window's figures over all its ads: `impressions`, `spend`, `clicks`, `ctr`, `currency`, and `daily_breakdown`, one entry per day with `date`, `impressions`, `spend` and `clicks`. `null` when its ads spend in two currencies; each ad then keeps its own. Absent for a creative with no ad. |
| `actions` | What you can do with it. See [Actions](https://docs.apostra.com/v3/creatives-list.md#actions). |

A creative that is not in the Library has `creativeId`, `name` (the name of
its top ad in Meta), `formatKind` and `mediaKind` when Apostra can tell what
kind of creative it is, and the fields above. Its `creativeId` is the id
[per-ad delivery](https://docs.apostra.com/v3/per-ad-delivery.md) assigns it, and `get` does not read it.

Each ad has:

| Field | Meaning |
| - | - |
| `platform` | `meta`. |
| `platformAdId`, `platformAdName` | The ad's id and name in Meta. |
| `campaignId` | The campaign the ad runs in. |
| `packageId` | The Meta ad set, in AdCP's package sense. |
| `runState` | `running`, `scheduled`, `in_review`, `rejected`, `paused` or `ended`. |
| `platformStatus` | Meta's own `effective_status`, as Meta sends it, or `null` when Meta no longer returns the ad. |
| `timezone`, `currency` | The ad account's timezone, which the ad's days are in, and its currency. |
| `delivery` | AdCP delivery metrics for the window, with the same fields as a per-ad delivery row: `impressions`, `spend`, `clicks`, `ctr`, `reach` with `reach_unit` and `reach_window`, `frequency`, and `conversions` when the ad set optimizes for an event. Reach and frequency stay on each ad because they do not add up across ads. |

For one ad's figures day by day, read
[per-ad delivery](https://docs.apostra.com/v3/per-ad-delivery.md) for its campaign.

### Run states

An ad's `runState` comes from Meta's status:

| Ad `runState` | When |
| - | - |
| `running` | Meta reports the ad `ACTIVE` and its campaign and ad set have started. |
| `scheduled` | The ad is `ACTIVE`, but its campaign or ad set has not started. |
| `in_review` | Meta is reviewing it (`PENDING_REVIEW`, `IN_PROCESS`). |
| `rejected` | Meta disapproved it (`DISAPPROVED`). |
| `paused` | It is paused, or its ad set or campaign is, or Meta reports any other status for an ad that is not spending. |
| `ended` | Its campaign or ad set has ended, or the ad is deleted or archived. |

A creative's `runState` follows from its ads. One running ad makes it
`running`, so a creative never shows as paused while it still spends. With no
running ad, a paused, scheduled, in-review or rejected ad makes it `paused`.
When every ad has ended it is `ended`. A Library creative with no ad is
`ready`.

`status` on a Library creative still means its approval by sellers, as it does
in every creative search.

### Tabs and counts

The response's `listStateCounts` counts every tab over the same read:
`all`, `running`, `not_running` and `not_in_library`. The tabs overlap: a
running creative that is not in the Library counts under `running` and
`not_in_library`. A page can show every tab's count from one call.

### Order and pages

Running creatives come first, then by the window's impressions, highest
first, then by `creativeId`. A page holds whole creatives, at most `limit` of
them and no more than fits the response. When there are more, `nextCursor`
is set: send it back with the same `listState` and `limit`.

## How the list is read

Apostra reads each Meta campaign of the advertiser that was in flight during
the window, live from Meta, through your connected ad account. One read
covers at most 50 campaigns, the most recently in flight first, 5 at a time,
and has 20 seconds in all.

That read is kept for 5 minutes, so paging and switching tabs do not read Meta
again and every page and tab of one list agree. A call without `cursor` within
those 5 minutes reuses it. A cursor names its read: once the read is no longer
kept, the cursor is refused with `INVALID_CURSOR`. Call again without `cursor`
to read the list afresh.

Two cases answer `SERVICE_UNAVAILABLE`, and a retry shortly after usually
succeeds. One is a list longer than one page whose read Apostra could not keep
for paging. The other is a read that could not finish within its 20 seconds
before reaching Meta, for example while loading your Library. A campaign that
runs out of time while Meta is being read is named in `coverage` instead, and
the rest of the list still answers.

The window is complete days in each ad account's timezone, named in
`deliveryWindow.timezones`. Apostra never shifts a day. When your ad accounts
are in more than one timezone, a creative's `daily_breakdown` adds up days
that begin at different moments; its totals are exact either way.

### Coverage

`coverage` says how complete the read is:

| `coverage.state` | Meaning |
| - | - |
| `complete` | Every Meta campaign in flight in the window was read. |
| `partial` | Some were not. `coverage.unread` names them, each with its `reason` and a `nextAction` that reads it with per-ad delivery. Rows and counts cover what was read: a campaign that was not read is missing, not zero. |
| `no_ad_account` | No Meta ad account is connected. The list holds the Library creatives, all `ready`, and `coverage.nextAction` is the `save_connection` call that starts connecting one. |
| `no_campaigns` | A Meta ad account is connected, but no Meta campaign of the advertiser was in flight in the window. |

An unread campaign's `reason` is `failed` (Meta or the connection did not
answer), `timed_out` (the read ran out of its 20 seconds) or `over_limit`
(past the first 50 campaigns). `coverage.inFlightCampaigns` counts every Meta
campaign in flight in the window, and `coverage.unread.count` every one not
read; `coverage.unread.campaigns` names up to 20.

## Actions

Each creative's `actions` lists the steps that apply to it. Each action names
an existing tool and the arguments to send, and `needs` lists the arguments
you add before calling.

| Action | On | Call |
| - | - | - |
| `link_to_library` | A creative not in the Library | `save_creative` with the ad's `campaignId` and `fromPlatformAd`. Add the `creativeId` of the Library creative it is. See [Link an ad to a creative in your Library](https://docs.apostra.com/v3/per-ad-delivery.md#link-an-ad-to-a-creative-in-your-library). |
| `add_to_campaign` | A Library creative | `save_creative` with its `creativeId`, `advertiserId` and the campaigns it is in now. Add the campaign to add to `campaignIds`. |
| `make_versions` | A Library creative with an image or video | `save_creative_session` with `advertiserId` and the creative's primary asset as `draft.source_asset`. Add an `idempotencyKey`. |

A creative that is not in the Library has no media in Apostra, so it is
offered `make_versions` only once it is linked or imported.

## What it does not cover

* Platforms other than Meta. TikTok has [per-ad delivery](https://docs.apostra.com/v3/per-ad-delivery.md)
  for one campaign at a time.
* Verdicts on each ad, such as which ads are tiring. They are coming, and
  will add a `tiring` tab.
* Delivery history beyond the last 30 days. Read
  [per-ad delivery](https://docs.apostra.com/v3/per-ad-delivery.md) for up to 90 days of one campaign.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.