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:
Apostra creates a Meta campaign paused and switches it on when its media buy
is activated, so until then Meta reports its ads
CAMPAIGN_PAUSED. That is
why an ad in a booked campaign that has not started reads scheduled, not
paused. When every booked media buy of the campaign is paused, you paused
the booking, and its ads read paused. Either way, platformStatus shows
Meta’s own 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 scheduled ad makes it scheduled: it is booked to run. With
neither, a paused, 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. A campaign is in flight when one of its media buys was booked or running during the window; a buy with no end date counts only while it is active, paused or ending. Apostra also reads each booked Meta campaign whose flight has not started, so its ads show asscheduled before they run. A campaign counts as booked when
one of its media buys is awaiting approval, active or paused with a start date
after the window, however far ahead. One read covers at most 50 campaigns:
those in flight first, most recently in flight first, then booked ones,
soonest start first. It reads them 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, coverage.scheduledCampaigns every booked
one that has not started, and coverage.unread.count every one of either 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.
Thumbnails for a page
A page that shows the list gets each Library row’s thumbnail in the result’s_meta, under scope3/creativeLibraryRenderUrls: a map from creativeId to
an image’s URL or a video’s poster frame. _meta is for the page and never
reaches the model, so the text and structuredContent carry no thumbnail.
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.