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

# What changed on a media buy?

> How to read the history of a media buy you booked through a storefront: one entry for every revision, who or what made the change, and what a buy that predates history shows.

A storefront gives every media buy you book through it one `revision` number. It
goes up by one each time the buy changes, whoever made the change. The history
answers the next question: what changed at revision 7, and where did the change
come from?

Ask for it with `include_history` on `get_media_buys`, the AdCP read a storefront
serves. Send a whole number from 1 to 1000. Each buy comes back with its latest
entries, newest first. Leave it out, or send 0, and the buy carries no history.

```json theme={null}
{
  "media_buy_ids": ["sf_mb_1"],
  "include_history": 5
}
```

> [!NOTE]
>
> The V3 `get` tool (`kind: "media_buy"`) does not return history today. Read it
> from the storefront's `get_media_buys`.

## What an entry says

```json theme={null}
{
  "media_buy_id": "sf_mb_1",
  "revision": 3,
  "history": [
    {
      "revision": 3,
      "timestamp": "2026-10-27T10:05:00.000Z",
      "action": "paused",
      "summary": "A connected platform reported the media buy as paused.",
      "ext": { "apostra": { "origin": "connected_platform" } }
    },
    {
      "revision": 2,
      "timestamp": "2026-10-27T10:02:00.000Z",
      "action": "updated_budget",
      "summary": "The buyer changed the budget.",
      "ext": { "apostra": { "origin": "adcp" } }
    }
  ]
}
```

| Field | Meaning |
| - | - |
| `revision` | The revision of the buy after this change. Every new revision has exactly one entry. |
| `timestamp` | When the change was committed. |
| `action` | What happened: `created`, `updated`, `updated_budget`, `activated`, `paused`, `resumed`, `completed`, `canceled` or `rejected`. Treat an action you do not know as `updated`. |
| `summary` | A short sentence in plain words. It never names the media partner or ad server behind the buy. |
| `actor` | Who made the change, when the storefront knows. The storefront does not set it today, so do not rely on it. |
| `ext.apostra.origin` | Where the change came from, below. |

## Where a change came from

| `origin` | Meaning |
| - | - |
| `adcp` | You or your agent: the buy was created, updated or canceled through a request you sent. |
| `connected_platform` | The media partner's platform reported the change, for example that it paused or completed the buy. |
| `seller_system` | The storefront's own handling, for example pausing a buy whose creation partly failed. |
| `seller_operator` | A person at the media partner made the change. The storefront does not use this value yet. |
| `unknown` | The storefront cannot say. |

`origin` is an AdCP 3.3 field. Storefronts here speak AdCP 3.2, so it travels as
`ext.apostra.origin` for now and moves onto the entry itself when Apostra moves to
AdCP 3.3. Treat an `origin` you do not know as `unknown`.

## What to rely on

* **Entries are never edited or removed.** Cache an entry by its revision.
* **You may get fewer entries than revisions.** `include_history` returns at most
  the number you ask for, applied to each buy. A buy that existed before history
  was kept has no entries for its earlier revisions, and its history starts at its
  next change. A missing entry for an old revision is not a missing change.
* **The history is the storefront's own.** It is numbered with the storefront's
  `revision`, the one you cite. A media partner's own history and revision numbers
  are not passed through.
* **Some storefronts do not return this history yet.** A storefront whose
  inventory runs through a platform adapter answers `get_media_buys` itself, and
  its answer does not carry the history described here.
* **A failed read is an error, not an empty history.** If the storefront cannot
  read the history it answers `SERVICE_UNAVAILABLE` with the reason
  `media_buy_history_unavailable`. Retry, or leave `include_history` out. See
  [Errors](https://docs.apostra.com/v3/errors.md) for how to read an error.

## Related

* [Does your buy still match the booking?](https://docs.apostra.com/v3/booking-answer.md): whether a buy
  still matches what you booked.
* [Errors](https://docs.apostra.com/v3/errors.md): how errors are reported.


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