progress include on a campaign or media buy:
goalProgress contains the campaign’s own goals, its media-buy
goals, and each package’s delivery goal. On a media buy, it contains that buy’s
goals and its packages’ delivery goals. The entries keep the exact scope in
scope.
Read a goal
EachgoalProgress entry describes one stored goal assessment.
For a cost-per goal,
verdictWithheld is terms_unavailable when a contributing
media buy has no pinned commercial terms. The cost and verdict are withheld
until those terms are available. Rate and volume goals do not require terms.
For these goals,
actual.trend contains up to seven daily cost or rate values
when the seller has reported compatible daily counts and denominators.
For a named vendor metric, advertiser records take precedence over seller values.
A rate is withheld when the matching daily delivery impressions are incomplete.
For an optimization entry, goal is the campaign or media buy’s native
AdCP optimization_goal, including its snake_case field names such as
event_sources, event_source_id, and metric_id. askedTarget and
answeredTarget are the target values the assessment compares; actual and
basis are Apostra’s calculated evidence for that comparison.
Within a delivery entry, values are null when the seller has not supplied
enough compatible data for that measure. For example, Apostra does not combine
spend that sellers reported in different currencies.
An on-pace result means the projected finish is within 2% of the binding
constraint, or within the projection’s measured uncertainty range, whichever
is larger.
Buys priced per rating point
A package priced per rating point (AdCPcpp) is judged on points instead of
spend. Its constraint.kind is grps and its amount is the ordered points:
the budget divided by the price per point the buy was accepted at. A media buy
with one such package is judged the same way.
Sellers report points as one total for a measurement window, such as live or
C3, and say when that total is final. There is no day-by-day points series, so
Apostra does not project points and deliveryProjection is null:
complete: the seller’s final points reached the ordered points.underdelivery: the flight has ended and the final points fell short.points_not_final: the seller has not called the points final yet. A provisional total never produces a verdict.too_early_to_judge: the final points are short of the order, but the flight has not ended.
get_delivery for the
grps metric grouped by media buy or package.
In get_delivery, each campaign and media buy on the page has a deliveryGoal
block, even before a stored delivery assessment exists. Its expected and
pacingIndex cover the dates you asked for. The projected finish and end state
come from the latest stored evaluation, so they match the goal progress returned
by campaign and media-buy reads.
If a seller media buy ID is shared by different buyer buys, Apostra withholds
the affected delivery pace with delivery_not_reported until it can attribute
the delivery to one buy. A campaign containing that buy is withheld too.
Package rating-point progress remains available from its own stored report.
The goal inside each non-null get_delivery goalProgress.*.progress is the
same native AdCP optimization_goal returned by the progress include. The
assessment remains bounded to the requested reporting range. Apostra returns a
goal only while the current campaign configuration exactly matches the stored
progress row. It returns null if the campaign goal changed or was removed,
or the stored row differs. The native object keeps AdCP’s snake_case field names
intact, including event_sources and metric_id. Event goals and goals with
native qualifiers are returned when those checks pass.
When the sweep has not yet stored a delivery assessment, deliveryGoal.verdict
is null and deliveryGoal.verdictWithheld is awaiting_confirmation. That is
a normal pending state, not zero delivery. The goal-progress sweep starts a
bounded refresh pass every 15 seconds. A candidate verdict must agree across two
consecutive evaluations using different reporting days before Apostra publishes
it. A buy’s final state appears as soon as its last day’s data arrives after
the flight ends. A published underdelivery or early exhaustion verdict remains until the
projection returns within half the tolerance. Use verdictWithheld to
understand what it means and what to do next:
no_budget_or_booked_impressions: the delivery goal has neither a spend budget nor booked impressions. Add a spend budget or booked-impression goal.no_flight: the delivery goal has no usable start or end date. Correct the flight dates.data_through_before_flight: available delivery data ends before the flight begins. Wait for in-flight delivery reporting, or correct the reporting dates.delivery_not_reported: no delivery has been reported yet. Retry after delivery is reported and check the seller reporting feed if it remains absent.too_early_to_judge: the available data is too early for a reliable projected finish. Wait for more delivery data.points_not_final: a buy priced per rating point has no final points total yet. Wait for the seller’s final report for the measurement window.awaiting_confirmation: the sweep has a candidate state that has not yet matched across two consecutive evaluations using different reporting days, or reached its final reporting day after the flight ends. This is normal just after a change; a verdict follows once new daily data arrives and confirms the candidate. Synthetic demo entries always show this value because demos never have a stored assessment.fx_rate_unavailable: a campaign needs a daily currency rate that is unavailable for the requested range. Retry once a rate is available or correct the currency setup.unavailable: a delivery-fact, currency-rate, or stored-assessment read failed. Retry later; this is never a judgement on the campaign.
progress can be null while deliveryGoal is populated. That means there
is no optimisation-goal progress to show, but Apostra still has delivery-goal
evidence for the campaign or media buy.
If a legacy report does not provide both dates for the reporting interval,
get_delivery omits goalProgress. Apostra cannot calculate interval
expected or pacingIndex without those dates.
sellerPacingIndex and sellerDeliveryProjection are seller-published values
that Apostra passes through unchanged. The delivery verdict is Apostra’s
assessment against the buyer’s goal: it does not edit, score, or certify the
seller, and it creates no seller-facing change or notification.
Show goal progress in a list
Use the same include withsearch:
progressSummary:
worstVerdict uses this order, from most to least serious:
underdelivery,behind, and other missed goalsearly_exhaustionon_paceandon_trackcompleteandbeat
worstVerdict is null.
The summary is deliberately small so a page of campaigns or media buys can be
read in one request. Use get when you need every goal and its evidence.
Keep a view current
Buyer agents can also subscribe tocampaign.progress.changed to learn when a published verdict changes.
Read again at nextCheckAt when it is present. A new seller delivery,
conversion event, goal, or budget change can also produce a new assessment.
The Apostra web app updates a changed goal assessment within about a minute.