> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Per-ad delivery

> Read how each ad in a Meta or TikTok campaign is doing, day by day: impressions, reach, frequency, clicks, spend and conversions, with the Apostra creative and Creative Session behind each ad.

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](https://docs.apostra.com/v3/per-ad-delivery.md#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:

```json theme={null}
{
  "report": "live_ad_delivery",
  "filters": { "campaignId": "cmp_123" },
  "range": { "startDate": "2026-11-01", "endDate": "2026-11-07" }
}
```

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:

```json theme={null}
{
  "report": "live_ad_delivery",
  "campaignId": "cmp_123",
  "currency": "USD",
  "reporting_period": {
    "start": "2026-11-01T04:00:00.000Z",
    "end": "2026-11-08T05:00:00.000Z",
    "timezone": "America/New_York"
  },
  "by_package": [
    {
      "package_id": "120210000000000001",
      "pricing_model": "cpm",
      "rate": 10.28,
      "currency": "USD",
      "impressions": 2400,
      "spend": 24.68,
      "clicks": 36,
      "ctr": 0.015,
      "conversions": 6,
      "by_event_type": [{ "event_type": "purchase", "count": 6, "value": 149.94 }],
      "by_creative_truncated": false,
      "by_creative": [
        {
          "creative_id": "cr_abc",
          "creative_in_library": true,
          "platform_ad_id": "120210000000000011",
          "platform_ad_name": "Gifting, warm table",
          "platform_creative_id": "120210000000000021",
          "creative_session_id": "cs_789",
          "creative_session_variant_id": "variant_2",
          "impressions": 1200,
          "spend": 12.34,
          "clicks": 18,
          "ctr": 0.015,
          "reach": 900,
          "reach_unit": "accounts",
          "reach_window": { "kind": "period", "period": { "interval": 7, "unit": "days" } },
          "frequency": 1.33,
          "conversions": 3,
          "by_event_type": [{ "event_type": "purchase", "count": 3, "value": 74.97 }],
          "daily_breakdown": [
            {
              "date": "2026-11-01",
              "impressions": 400,
              "spend": 4.11,
              "clicks": 6,
              "ctr": 0.015,
              "reach": 350,
              "reach_unit": "accounts",
              "reach_window": { "kind": "period", "period": { "interval": 1, "unit": "days" } },
              "frequency": 1.14,
              "conversions": 1,
              "by_event_type": [{ "event_type": "purchase", "count": 1, "value": 24.99 }]
            }
          ]
        }
      ]
    }
  ],
  "page": { "limit": 100, "returned": 2, "total": 2, "truncated": false, "consistency": "live_per_call" },
  "authority": "live_provider"
}
```

### Each ad

| Field | Meaning |
| - | - |
| `creative_id` | The creative the ad runs, always set. For an ad Apostra made, it is the Apostra creative. For an ad made in the platform's own tools, it is an id Apostra assigns to that creative (see below). |
| `creative_in_library` | `true` when `creative_id` is a creative in your Apostra Library, which `get` with `kind: "creative"` reads. `false` when Apostra assigned the id. Use this field to tell them apart, not the id's format. |
| `platform_ad_id`, `platform_ad_name` | The platform's id and name for the ad. |
| `platform_creative_id` | The platform's id for the creative the ad runs: Meta's creative id, or on TikTok the id of the material the ad runs. `null` for a deleted ad the platform no longer returns. |
| `creative_session_id`, `creative_session_variant_id` | The Creative Session, and the variant in it, that made the Apostra creative. `null` when no Creative Session made it. |
| `impressions`, `spend`, `clicks`, `ctr` | Totals over the whole range. Clicks are the same clicks `live_campaign_delivery` reports: on Meta, clicks that leave Meta for your site. `ctr` is clicks divided by impressions. |
| `reach`, `frequency` | Unique accounts (Meta) or people (TikTok) reached over the whole range, and the average number of times each saw the ad. `reach_unit` says which. |
| `conversions`, `by_event_type` | The conversion event the ad's package is optimized for, such as purchases, with its value when Meta reports one. |
| `daily_breakdown` | One row per day the ad delivered, with the same figures for that day. |

### 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](https://docs.apostra.com/v3/per-ad-delivery.md#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](https://docs.apostra.com/v3/import-existing-campaigns.md#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`:

```json theme={null}
{
  "creativeId": "<your Library creative>",
  "campaignId": "<the campaign the ad runs in>",
  "fromPlatformAd": { "platformAdId": "<platform_ad_id from this report>" }
}
```

* **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](https://docs.apostra.com/v3/creative-loop-by-destination.md). 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

| Code | When |
| - | - |
| `VALIDATION_ERROR` | No `campaignId`, a lifetime range or one longer than 90 days, metrics, dimensions or other filters sent, or a campaign on a platform that does not offer per-ad delivery (see `reason` above). |
| `NOT_FOUND` | The campaign does not exist in your account. |
| `INVALID_CURSOR` | The cursor came from a different request, or was changed. Send it back exactly as you received it, with the same campaign, dates and limit, or start again without it. |
| `SERVICE_UNAVAILABLE` | The platform did not answer, or its connection needs attention. Retry shortly; if it keeps failing, check the connection in Settings. When the platform cannot return the whole range within 50 seconds, the message names the range: read a shorter one, for example 7 days at a time. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.