Read per-ad delivery
Callget_delivery with report: "live_ad_delivery", one campaign and a date
range of at most 90 days:
What comes back
The response follows AdCP’s delivery shape. Ads sit inside their packages, the way AdCP nestsby_creative inside by_package. A package is a Meta ad set
or a TikTok ad group. This example is from Meta:
Each ad
Each package
Eachby_package entry is a Meta ad set or a TikTok ad group. Its figures are
the sums of its ads. It has no reach or frequency, because those do not add up
across ads.
Ads made in the platform’s own tools
An ad that runs a creative Apostra did not make, for example one you built in Meta Ads Manager or TikTok Ads Manager from your own media, is not in your Library. Apostra still gives it acreative_id, as AdCP has a seller do for a creative it made itself, and marks
it creative_in_library: false:
- One id per platform creative. The same creative gets the same
creative_idon every read and in every ad that runs it, so you can group and compare ads by creative. getdoes not read it. Apostra holds no copy of the creative.getwithkind: "creative"and this id answersINVALID_STATEwith the reasoncreative_not_in_library, notNOT_FOUND. The answer says what ids of this form are; it does not confirm that the id names a real creative, so read the ad’s row in this report for that. The ad’s figures are all here.- A deleted ad. If the platform no longer returns a deleted ad, it no
longer says which creative the ad ran. That ad’s
creative_idis assigned from the ad instead, andplatform_creative_idisnull. TikTok differs: see On TikTok.
Link an ad to a creative in your Library
Apostra imports the creatives of ads made in Meta Ads Manager into your Library by itself when it syncs the ad account’s campaigns, and an imported creative is already linked: this report names it from the next read. See The creatives of your Meta ads. When an ad made in Meta Ads Manager runs a creative you already have in your Library, link the two so this report names your creative. Callsave_creative
with the Library creative, the campaign the ad runs in and the ad’s
platform_ad_id:
- What changes. From the next read, this report gives every ad that runs
that Meta creative your
creative_idwithcreative_in_library: true, for the whole range, earlier days included. - What it does not do. A link copies no media and creates no creative. It does not attach the creative to the campaign, because the ad already runs there.
- Which ads. Meta only, for now. The ad must run in the campaign you name,
and be a single image ad linked to an image creative, a single video ad
linked to a video creative, or a dynamic creative ad that Apostra can read as
an AdCP responsive creative, linked to a
responsive_creative. A carousel, a catalog ad, or a dynamic creative Apostra cannot read that way is refused withVALIDATION_ERROR. An ad that is not in the campaign answersNOT_FOUND. - Already linked. Linking an ad again to the same creative changes nothing
and answers
alreadyLinked: true. If its Meta creative is already another creative of yours, the call answersCONFLICTnaming that creative.
Things to know
- Days with no delivery are missing, not zero. The platform returns no row for a day an ad did not deliver. The ad’s totals already count those days as zero.
- Reach does not add up. Never add daily reach to get the reach for the
range: the same person can be counted on several days. Use the ad’s own
reach, which counts each person once over the range. - Totals and reach come from two reads. An ad’s totals are the sums of its days. Its reach and frequency for the range come from a second read made in the same call, so on a campaign that is delivering they can be a few impressions ahead or behind.
- Conversions are the package’s optimization event only. A package that is
not optimized for a conversion event has no
conversions. The platform can still revise conversions within its attribution window, so a later read can differ. - Creative Session names. When a Creative Session finishes a creative, Apostra records the session and variant on the creative, so its ads name them for as long as they run. A creative finished before Apostra kept that record (November 2026) names them only while its session is still kept, which is 7 days after the session was created.
- Meta and TikTok, for now. Which platforms offer per-ad delivery is
listed on Creative loop by destination. A
campaign on any other platform is refused with
VALIDATION_ERROR, a message that names the platform, and areasonin the error’s details:not_builtwhen Apostra has not built it for that platform yet,destination_cannotwhen the platform’s own API offers no ad-level figures, andnot_declaredwhen the campaign is not on an ad platform, such as a campaign bought from a seller’s sales agent. - Live, not billing. These are the platform’s figures at the time of the call. They are not Apostra’s reporting figures and are not used for billing.
On TikTok
TikTok works as above, with these differences:- Packages are ad groups.
package_idis the TikTok ad group id, and each ad is a TikTok ad. - Material, not creatives. TikTok has no creative object: an ad runs a
video, an image, a carousel of images or a Spark post.
platform_creative_idis that material’s id: the video id, the image id, the post’s item id, or the first image id of a carousel.creative_in_librarysays which creative an ad runs, not who built the ad: an ad reads as your Apostra creative when it runs exactly the material Apostra uploaded for it, the same kind and, for a carousel, every image in the same order. That holds wherever the ad was built, so an ad you make in TikTok Ads Manager from that material reports your Apostra creative. Reusing part of it, such as one image from a carousel, does not count. - Assigned ids carry the kind of material. An assigned
creative_idon TikTok looks liketiktok_creative_video_followed by a short code. The same material gets the same id on every read. An ad that runs no reusable material, such as a catalog carousel or a LIVE ad, is assigned an id from the ad. So is an ad whose material TikTok describes in a form Apostra cannot read: its delivery is still reported, and itsplatform_creative_idisnull. - Deleted ads. Apostra asks TikTok for deleted ads too, so a deleted ad reads like any other, with its creative and ad group. An ad TikTok does not return at all is left out of the read, because Apostra cannot confirm it ran in this campaign.
- Reach counts people.
reach_unitisindividuals. - Range reach can be absent. TikTok reads daily figures 30 days at a
time, so a 90-day read makes three requests. Reach over the whole range comes
from one more request. If TikTok refuses it, as it may for a range longer
than 30 days, or that request fails, the ads’ range
reachandfrequencyare absent; their daily rows still carry them. Never add the days up to get reach. - Conversions.
conversionscount the ad group’s optimization event when that event has an AdCP name, such as purchase or lead. TikTok reports no conversion value here, soby_event_typehas novalue.
Paging
Packages come inpackage_id order and their ads in platform_ad_id order. A
page holds whole ads, up to limit ads (100 by default) and as many as fit in
one response. When more ads remain, page.truncated is true and
page.nextCursor is set: call again with the same request and
cursor set to that value. A package split across pages appears on each page
with the same totals and by_creative_truncated: true. Each page reads the
platform again.