Skip to main content
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:
Send filter.campaignId instead of filter.advertiserId to list only the creatives of one campaign and that campaign’s ads. 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: 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 assigns it, and get does not read it. Each ad has: For one ad’s figures day by day, read per-ad delivery for its campaign.

Run states

An ad’s runState comes from Meta’s status: 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: 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. 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 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 for up to 90 days of one campaign.