Skip to main content
When Apostra’s optimizer works across a whole campaign rather than one media buy at a time, its recommendations stop being independent. Taking budget out of one media buy is what funds putting budget into another, so the two halves are one decision. A campaign suggestion set is that decision: every media buy the optimizer moved money between, grouped under the single run that computed them.
If you are not receiving sets yet, nothing is missing — see Availability.

​
Why a set is approved as a whole

Each member of a set carries a netAllocationDelta — the amount that media buy gains or gives up. Those are transfers, not standalone recommendations, and they sum to exactly zero across the set. That is why there is no way to approve one media buy’s share on its own. Approving a +4000 minor units without its offsetting -4000 would create budget that the campaign never freed; approving the -4000 alone would strand it. And rescaling a subset so it balances by itself produces an allocation the optimizer never evaluated against your goals or your sellers’ capacity. So the set is the unit: you approve all of it, or none of it. The per-media-buy breakdown is there so you can see what the transfer does — read a single set to get it. It is not there so that parts of it can be actioned separately.

​
The lifecycle of a set

1

Awaiting messages

The optimizer publishes one message per media buy it evaluated, and they arrive independently. Until all of them have, the set is incomplete and Apostra will not act on it — applying half a transfer would leave your campaign’s budget unbalanced. A set can sit here legitimately while the rest of the run arrives.
2

Awaiting approval

The set is complete and balanced, and it is yours to decide. You are notified when a set reaches this state.
3

Approved or rejected

Your decision applies to the whole set. Approve it, or reject it — rejection optionally carries a reason; approval takes no body.
4

Applied

Apostra sends the changes to your sellers and waits for each one to take effect. This is not instant — see What happens after you approve.
If optimizations are set to apply automatically, a complete set goes straight to approved without waiting for you. That setting is read from the campaign, falling back to the advertiser’s default when the campaign does not set one — so a set can auto-approve on a campaign that appears to specify nothing. It is fixed when the run is first seen, so changing it mid-run affects the next run, not one already in flight.

​
What happens after you approve

Approving does not move the money. It clears Apostra to move it, and the move takes time, because each media buy lives at a different seller and a seller takes a change when it takes it. Two things about that are worth understanding, because they are what you will see while polling. Budget is freed before it is spent. Every media buy giving budget up is changed first, and Apostra waits until each seller has actually enacted its decrease before sending a single increase. It never commits budget the campaign has not yet freed. That waiting is the reason a set stays in APPLYING for a while, and it happens twice — once for the decreases and again for the increases. How long that takes is up to your sellers: often minutes, longer when one queues the change for review. Apostra keeps checking rather than assuming, and if a seller goes quiet it stops and raises the set for a person rather than waiting indefinitely. If a change cannot be made, the whole transfer is put back. A set is one decision, so it is applied as one. If a media buy’s change fails after another buy’s change has already landed at its seller, Apostra restores every media buy it had already moved to the budget it held before the set was applied. The one exception is a reversal that cannot itself complete — a seller refuses the undo, or never enacts it. Apostra then stops rather than guessing, moves the set to NEEDS_RECONCILIATION, and a person puts the budgets right. Until they do, your live budgets can sit part-way between the suggestion and their pre-approval values; see the statuses below.
A media buy whose flight has ended while the set was applying is left out — of the transfer, and of the reversal too. A finished buy cannot spend what a budget change would give it, and failing the set over one would undo the other buys’ correct changes over a calendar date. The set still completes and names the media buys it left out, on statusReason.The exception is a media buy that was giving budget up. If its flight ends before its seller has enacted the decrease, that budget was never freed — the buy may already have spent it — so Apostra does not send the increases it would have funded. The whole transfer is put back instead, and a later run re-plans the campaign without the finished buy.When a finished buy is left out, your budgets will not match either the suggestion or their pre-approval values exactly. A buy left out of a reversal may still be sitting at the applied budget, and because its flight has ended, nothing further will change it.

​
Statuses you may see

Only AWAITING_APPROVAL is actionable by you. Everything else is either in progress or terminal. NEEDS_RECONCILIATION is the one status where your live budgets may not match either the suggestion or their pre-approval values. Apostra is alerted automatically and resolves it; you do not need to open a ticket. Do not hand-edit the affected media buys’ budgets while a set is in this state — doing so changes what Apostra is working from to put them right. The status filter accepts the full enum. Treat an unrecognised status as “not actionable by me” rather than assuming this list is closed.

​
Finding sets that need you

List campaign suggestion sets and filter on status=AWAITING_APPROVAL to see just the decisions outstanding. You can also filter by campaignId. The list gives you each set’s campaignMediaBuyCount but not its per-media-buy breakdown — a single campaign can span many media buys, and a list is for finding the set you care about. Fetch that one set to see where the money goes. campaignMediaBuyCount is the number of media buys the optimizer declared for the run, not the number reported so far. A set still in AWAITING_MESSAGES can declare four and return an empty mediaBuys array, because membership is fixed only once the set is complete.

​
How a set relates to a suggestion

A campaign suggestion set is made of ordinary optimization suggestions — one per member media buy — and each still appears through GET /api/v2/buyer/optimization-suggestions as usual. What changes is where the decision lives: a suggestion that belongs to a set cannot be approved or rejected on its own, and attempting it returns 409 naming the set to decide instead.

​
Availability

Campaign-scoped optimization is being rolled out. No campaign-scoped runs are published yet, so these endpoints return nothing for anyone — they filter nothing by account, and an empty list today is not a statement about your rollout. Once runs are published, an account that is not yet enabled will have its sets recorded rather than acted on, whether or not the campaign applies optimizations without review, and no approval notification arrives for the ones you would otherwise have reviewed. Nothing about your existing per-media-buy optimization suggestions changes in the meantime.