Read the list
Callsearch with kind: "creative", include: ["delivery"] and the
advertiser:
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’srunState 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’slistStateCounts 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 bycreativeId. 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 withoutcursor 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’sactions 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
tiringtab. - Delivery history beyond the last 30 days. Read per-ad delivery for up to 90 days of one campaign.