Skip to main content
Per-ad delivery shows how every ad in one campaign performed over a date range, one row per ad per day. Use it to see which ads are winning and which are tiring, for example when frequency climbs while click-through falls. Each ad names the creative it runs, including ads made in the platform’s own tools, and, when a Creative Session made it, the session and the variant you picked, so you can tell which concept worked. It is available on Meta and TikTok. It reads the campaign from the platform on every call, through your connected ad account. It covers campaigns you bought through Apostra and campaigns you connected from your own ad account. What differs on TikTok is under On TikTok.

Read per-ad delivery

Call get_delivery with report: "live_ad_delivery", one campaign and a date range of at most 90 days:
The dates are calendar days in the ad account’s timezone, which the response names. A lifetime range, metric selection, grouping dimensions and other filters are refused: this report always returns every figure below for every ad.

What comes back

The response follows AdCP’s delivery shape. Ads sit inside their packages, the way AdCP nests by_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

Each by_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 a creative_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_id on every read and in every ad that runs it, so you can group and compare ads by creative.
  • get does not read it. Apostra holds no copy of the creative. get with kind: "creative" and this id answers INVALID_STATE with the reason creative_not_in_library, not NOT_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_id is assigned from the ad instead, and platform_creative_id is null. TikTok differs: see On TikTok.
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. Call save_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_id with creative_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 with VALIDATION_ERROR. An ad that is not in the campaign answers NOT_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 answers CONFLICT naming 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 a reason in the error’s details: not_built when Apostra has not built it for that platform yet, destination_cannot when the platform’s own API offers no ad-level figures, and not_declared when 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_id is 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_id is 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_library says 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_id on TikTok looks like tiktok_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 its platform_creative_id is null.
  • 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_unit is individuals.
  • 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 reach and frequency are absent; their daily rows still carry them. Never add the days up to get reach.
  • Conversions. conversions count the ad group’s optimization event when that event has an AdCP name, such as purchase or lead. TikTok reports no conversion value here, so by_event_type has no value.

Paging

Packages come in package_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.

Errors