> ## 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.

# Campaign Pulse

> Check whether a campaign is actually running, from the latest provisional figures its sellers reported, and what each verdict means.

Campaign Pulse answers one question: is there fresh evidence that a campaign is
running? A campaign can be active and still deliver nothing, for example when a
seller has not started its line or a creative was rejected. Pulse looks at the
figures each seller reported, not at the campaign's status.

Pulse is provisional. It reads Snapshot figures, which are not final and not
billable. Official reporting, the final figures a seller publishes, is a
separate read: see [Reporting](https://docs.apostra.com/v3/reporting-pipeline.md).

## Read Pulse

Ask for the `pulse` include on a campaign:

```json theme={null}
{ "kind": "campaign", "id": "cmp_123", "include": ["pulse"] }
```

`get` returns `pulse` with the campaign's verdict, its reasons, and one entry
for each media buy Pulse judges (at most 50; `mediaBuysOmitted` counts the
rest). Those are the campaign's active media buys, and its media buys that
ended in the last 90 days whose delivery is behind (below). Draft, paused and
archived media buys are not listed, nor is an ended one whose delivery runs to
its flight end.

Each media buy entry has:

| Field | Meaning |
| - | - |
| `verdict` | The media buy's verdict (below). |
| `reasonCodes` | Why it has that verdict, for example `snapshot_missing`. |
| `dataThrough` | How far the seller's figures run: the later of its latest provisional figures and the end of the last day of daily delivery Apostra holds. It stops at the end of the flight's last day, unless the seller reported impressions or spend after the flight ended. A seller that still reports an ended media buy as running sends days of zeros, and those do not move it past the flight. `null` when Apostra has received nothing yet. |
| `observedAt` | When Apostra received the provisional figures. |
| `freshness` | `fresh`, `stale` or `missing` (nothing received yet), and the `deadline`: when the next day of delivery falls due. For a stale media buy it has passed; it is `null` once the delivery runs to the flight end. |
| `metrics` | Impressions, clicks and spend, each with an `availability`: `present`, `explicit_zero` (the seller reported zero), or a reason it has no value such as `missing`. |

To show Pulse in a list, ask `search` for it:

```json theme={null}
{ "kind": "campaign", "include": ["pulse"] }
```

Each campaign row then carries `pulse` with only the campaign `verdict`,
`dataThrough` and `nextCheckAt`.

If Pulse cannot be read, the campaign is still returned, and
`unavailableIncludes` names `pulse` with the reason.

## What each verdict means

For a media buy:

| Verdict | Meaning |
| - | - |
| `delivering` | Fresh figures show impressions or spend. |
| `not_delivering` | Fresh figures show zero, reported as zero by the seller. |
| `stale` | Days of delivery its reporting schedule makes due are missing after the last day Apostra holds. That is missing data, not zero delivery: the seller may still be delivering. |
| `unsupported` | The products this buy booked do not report impressions, clicks or spend. |
| `source_error` | The seller's latest report failed. |
| `not_expected_yet` | The flight has not started, or its first day of delivery is not due yet. |
| `unverified` | Its delivery is not behind, but there are no usable figures to judge it by: the figures are incomplete or not received yet, or its products declare no reporting schedule. |

For the campaign:

| Verdict | Meaning |
| - | - |
| `not_expected_yet` | No live media buy has started, or the campaign has none. |
| `delivering` | Every started media buy is delivering. |
| `partially_delivering` | At least one is delivering and at least one is not. |
| `not_delivering` | None is delivering, and every started one reported zero. |
| `cannot_verify` | None is delivering, and at least one is stale or has no usable figures to judge. |

Missing figures are never shown as zero. A media buy whose seller has not
reported reads `not_expected_yet` until its first day of delivery is due, and
`stale` after that, never `not_delivering`, and its metrics are `null`. Two
media buys read otherwise: one whose products do not report delivery reads
`unsupported`, and one whose seller's latest report failed reads
`source_error`.

## When figures are due

Whether a media buy is stale is the same calculation `get_delivery` reports as
`deliveryFreshness`, so Pulse, the Campaigns page and `get_delivery` always
agree. See
[How current each seller's delivery is](https://docs.apostra.com/v3/reporting-pipeline.md#how-current-each-sellers-delivery-is).

* **The schedule.** It comes from the products the media buy booked: how often
  each product reports (`available_reporting_frequencies`) and how long after a
  period ends its report arrives (`expected_delay_minutes`). The most frequent
  schedule any of them reports on applies, with the longest delay.
* **When a day is due.** Reporting periods run from the day after the last day
  of daily delivery Apostra holds, and a period is due once it has ended and its
  delay has passed. When the products declare no schedule, a day is due two days
  after it starts.
* **Stale.** A media buy is stale when a due day in its flight has no delivery
  after the last day held. A day the seller reported as zero is held, so zero
  delivery is not stale. A media buy whose delivery runs to its flight end is
  never stale.
* **Ended media buys.** One whose delivery stops before its flight ended stays
  on Pulse as stale for 90 days after the flight ends. After that its gap still
  shows in `get_delivery`.

Some sellers' figures arrive sooner than that. When a seller sells Google Ad
Manager (GAM) inventory through the sales agent Apostra runs for it, Pulse also
uses each live media buy's package snapshot: the impressions, clicks and spend
GAM has counted since the flight started. The agent refreshes the snapshot from
GAM about every 15 minutes, and Apostra reads it every 5 minutes, so new figures
reach Pulse within about 5 minutes of the agent capturing them. A media buy is
read this way from the start of its flight for as long as the seller reports it
active.

When the snapshot is newer than the seller's latest daily report, Pulse shows
the snapshot, and its `dataThrough` and `observedAt` are the time the agent
captured it (for a media buy with several packages, the oldest of their capture
times). Once the daily reports run past it, Pulse shows them again. Either way
the figures are provisional. See
[How often GAM delivery arrives](https://docs.apostra.com/v3/reporting-pipeline.md#how-often-gam-delivery-arrives).

## Keep a view current

Buyer agents can also subscribe to [`campaign.progress.changed`](https://docs.apostra.com/v3/webhooks#campaignprogresschanged) to learn when a published verdict changes.

`nextCheckAt` is the earliest time a verdict can change with no new report: a
flight starting, a day of delivery falling due, or an ended media buy leaving
Pulse after its 90 days. It is `null` when only a new report can change a
verdict. To keep a page current,
read Pulse again at `nextCheckAt` rather than on a timer.

## Pulse on the Campaigns page

The Campaigns page shows Pulse without being asked. Each campaign in the list
carries its verdict and how far its data runs ("Data through", or "No data yet"
when no seller has reported). Opening a campaign shows its verdict, then each
listed media buy's verdict, its data-through time and its impressions, clicks
and spend. The page labels these as provisional Snapshot figures, not official and
not billable.

A figure a seller has not reported shows as "Unavailable" with the reason (not
reported, delayed, incomplete or out of date), never as 0. Only a figure the
seller reported as zero shows as 0.

In the Apostra web app, the page updates as soon as a campaign's Pulse changes:
when a new report changes a verdict, or figures go stale, the list and the
opened campaign show it within about a minute, without a reload. The page only
watches for changes; it reads the new Pulse the same way it did the first time,
so it never shows a campaign you can't otherwise see. In Claude, ChatGPT and
other hosts, the page reads Pulse again at `nextCheckAt` instead. It does not
poll on a timer in any host, and in the web app it also keeps that
`nextCheckAt` check as a fallback.

## Pulse and budgets

Pulse gives a delivery verdict. It does not give pacing figures, and Apostra
does not make budget recommendations from it.


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