These are different data products. A CSV aggregate is not a raw event feed, and
a notification is not a reporting export.
1. Prove access and choose the report
For MCP, callget_status and verify the active account. Inspect the current
get_delivery schema before choosing a report.
- A Buyer Account uses
report: "live_campaign_delivery"for one exact connected-provider campaign, orreport: "campaign_delivery"for stored aggregate rows. - A Seller Account uses
report: "delivery"for seller-reported delivery, orreport: "margin"for its cumulative spread ledger. - An integrated Media Company can also read
live_campaign_deliveryfor one exact own-supply campaign. This does not grant a Seller credential general access to Buyer REST reporting.
2. Read a bounded delivery window
For a stored Buyer Account aggregate, callget_delivery:
range: {"lifetime": true}; a packageId filter requires
a bounded range instead. Follow the returned pagination contract until all
requested rows are read.
Delivery summaries label explicit periods as UTC dates. They do not convert the
requested reporting range to a campaign or advertiser timezone.
Metrics use AdCP’s delivery metric names:
A metric the seller did not report is returned as unavailable, never as zero.
Viewability, for example, is unavailable for delivery whose seller measured none.
Every row and total carries a
finality label: Official (final, eligible for
billing), Snapshot (provisional), or unavailable when the delivery has no
revision evidence. Figures of different finality are never added together.
Rows are split by finality, and when matched delivery spans more than one
class, totals gives no figure (each metric reads finality_mixed) and
totalsByFinality gives one total per class.
Join package rows to your own data
Withpackage in dimensions, each campaign_delivery row names its package
in rows[].dimensions.package:
When one creative serves several packages, the seller fills a
{PACKAGE_ID}
macro with its own id, so your landing pages and trackers may receive the
seller’s id rather than ours. Match the id your URL carries against id or
sellerPackageId, whichever it is. In AdCP’s own delivery report, the seller’s
id is by_package[].package_id.
For the current connected-provider response instead, use the additive live
mode:
LIVE_PROVIDER_UNAVAILABLE instead of NOT_FOUND. The response
lists the campaign’s buys under details.mediaBuys with each buy’s status
(such as canceled) and, when one is recorded, an errorCode (such as
source_unavailable). The list holds at most 25 buys, newest first;
details.mediaBuyCount is the total, so a count above 25 means the list is
cut short. Tell
the person there is nothing live to report. Use campaign_delivery for
delivery stored before the buys ended. NOT_FOUND still means the campaign
does not exist in the active account. If Apostra cannot check the campaign’s
state at that moment, the call returns a retryable SERVICE_UNAVAILABLE
instead, and neither answer is known.
The same LIVE_PROVIDER_UNAVAILABLE answer covers a campaign that has not
started delivering yet. When the provider cannot return delivery, whatever the
way it fails (a refusal, a failed or incomplete report, an error), and every buy
is either waiting to start (a draft, pending approval, or a flight start still
ahead) or has ended, the message says what each waiting buy is waiting on, for
example that no creatives are attached yet, and the start time of a flight that
has not begun. Tell the person nothing has delivered yet, and read live delivery
again once the flight has started. A campaign with any buy whose flight has
started does not get this answer, and neither does a refused credential or a
rate limit, which keep their own errors. If the provider can answer, including
with zeros, its answer is returned.
If the provider refuses the read for a campaign that has started, the call
returns SERVICE_UNAVAILABLE with details.reason of
provider_rejected_delivery_read and the provider’s own code in details.code.
This is the provider’s answer, not a statement that your input is wrong: the
read carries only the campaign and the date range you gave. Retry later, and if
it keeps failing, check the campaign at the provider or contact support. A
refused credential is a different failure and keeps its own error.
A campaign whose media buy has no stored provider route or identity cannot be
read at all, and retrying cannot change that. The call returns
SERVICE_UNAVAILABLE with details.reason of
provider_media_buy_identity_missing, recovery: "terminal" and a suggestion
not to retry. Use campaign_delivery for delivery stored earlier, and ask
Apostra Support to repair the media buy’s provider binding or recreate the
campaign. Use the
buyer or
seller reference for
the report available to your account.
Preserve the report type, account and resource scope, requested dimensions or
provider reporting period, currency, and time of extraction with the result.
Read delivery by site or app
Addproperty to the dimensions of a stored campaign_delivery read to see
which sites and apps your ads ran on, with the property scores you saved in force
on each day. Use it to check that a score floor held, for example that no
impression ran on a site scored below 20.
property is a Buyer Account read of your own media buys, and it is in the
buyer beta: an account that is not on the beta gets FEATURE_NOT_ENABLED. Your
property scores themselves are not part of the beta.
It always needs date, because a row is one property on one UTC day. It can
also be split by media_buy and package, which are the only other things the
tracker records. impressions is the only metric, because a row has no spend or
other measure. A call that asks for anything else is refused with a message
naming the field, never answered with part of it dropped: another dimension or
metric, a currency, a productId filter, or a lifetime range. Use a
bounded range of at most 90 days. The advertiserId, campaignId,
channelGroupId, mediaBuyId and packageId filters narrow the read.
The request still names report: "campaign_delivery", but the answer has
report: "campaign_property_delivery", because its rows are a different shape
from the stored seller rows. Read report to tell the two answers apart. The
answer has no totals: a row can count an impression that also appears in the
row of another property, so rows do not add up.
Each row is one property on one day:
Scores follow your saved history. A score saved or changed during a UTC day
counts for that day, and one saved at the next midnight does not. A day before
the first save has no score, and nothing is backfilled. An exact host wins over
its registrable domain for the same feature. Apps get no score yet: scores for
apps will follow once the tracker can record which store an app comes from.
The response also carries
propertyDelivery, with one entry per seller that had
tracker impressions in scope, over the whole range and not only the returned
page:
propertyDelivery.mediaBuysRead counts the buys in scope the tracker could be
asked about. A buy whose tracker id another account also holds is not read.
What tracker rows can and cannot show
- Only buys that reach our tracker. A row exists only where an impression
fired our pixel and the seller’s ad server filled the site or app macro
(
{DOMAIN}or{APP_BUNDLE}). A buy whose creatives do not fire our pixel, such as a format with no slot for it, is missing. A seller that does not fill the macro leaves part of its delivery with no property. Snap’s own ad formats are one example: Snap has no field on a creative for a third-party impression pixel, so Snap buys never appear in these tracker-sourced rows. Their delivery still reads normally throughget_delivery, from Snap’s own reporting; only the property-level breakdown above is unavailable for them. - Fill share says how much of a seller’s delivery the rows can see. Only a
fillShareof 1 shows every tracked impression’s site or app, so only then does a site with no row mean the ad did not run there. Below 1, some impressions carried no site or app and could have run anywhere, including on a site with no row: a high share gives confidence, not proof. A low share shows where the ad ran only in part. When neither source covers a flight, the result for a floor is inconclusive, not clean. - Estimated, not billable. Counts follow the certification basis: impressions only, duplicate pings of one impression counted once, and crawler hits removed. They can differ from what the seller reports and bills. Hits from roughly the last hour may not be readable yet.
- Impressions only. Clicks never produce rows, and an impression that carried neither a site nor an app produces none. An impression that carried both a site and an app is counted in the row of each, so do not total rows across properties.
- Your own buys. The read covers the media buys of your account, with no minimum group size, because you see only your own delivery.
- Bounded. A page holds at most 100 rows; follow
nextCursoras for anycampaign_deliveryread. A read covers at most 1,000 media buys and 50,000 tracker rows; when it would exceed either, narrow the range or the buys.
3. Preserve what the data means
Your consumer should carry coverage, warnings, finality, and unavailable values alongside the numbers. Do not turn a missing source value into zero or describe seller-reported delivery as independent buyer measurement. Finality alone is not evidence that an amount is eligible for billing. A storedcampaign_delivery read returns rows only for campaigns whose delivery
has reached Apostra. An account-wide read can therefore leave out a campaign
that was in flight during the range. That campaign is missing, not at zero.
On an account-wide read over a bounded range, the response carries coverage
so you do not have to work out which campaigns are missing:
inFlightCampaignscounts the campaigns in scope with a current media buy that was booked or running during the range. Draft, failed, rejected and canceled buys do not count. A buy with no end date counts only while it is active, paused or ending.withoutStoredRowslists the in-flight campaigns that have no stored rows, up to 20.countis the full number, andtruncatedis true when the list is shorter thancount.- Each
nextActionis the exact call that reads that campaign from its connected provider. The stored rows, totals and paging are unchanged.
coverage appears only when the read is account-wide: a bounded date range with
no filter other than advertiserId. An advertiserId filter narrows the list
to that advertiser. A read filtered to one campaign, media buy, package,
product or channel group, and a lifetime read, return no coverage.
How current each seller’s delivery is
A seller’s delivery reaches Apostra on the schedule its products declare: a day or two after the day it covers for a daily reporter, or after each week for a weekly one. If a seller stops sending it, the media buy has no rows for the days since, and a read cannot show that as zero. So every storedcampaign_delivery response carries deliveryFreshness, which says, for each
media buy in scope, the last day Apostra holds delivery for, the day its
delivery is due through, and whether it is behind:
When delivery is due. Each buy is judged against the reporting schedule its
products declare in their reporting capabilities: how often they report
(
available_reporting_frequencies) and how long after a period ends the report
arrives (expected_delay_minutes).
- A product reports at the frequency the media buy asked for when it offers that frequency, and otherwise at the most frequent one it lists. When a buy’s products differ, the most frequent of them applies, and the longest delay.
- Periods run back to back from the day after
lastDayHeld, or from the flight start when Apostra holds nothing. Hourly and daily periods are one day, weekly seven, monthly 31 and quarterly 92. - A period is due once it has ended and its delay has passed.
dueThroughis the last day of the last due period. When the flight ends inside a period, the days up to the flight end are due once the flight has ended and the delay has passed. - When a buy’s products declare no schedule, a day is due two days after it starts: on 10 November, delivery is due through 8 November.
- A stale buy is missing data, not zero delivery. Its seller may still be
delivering. Treat its rows as incomplete after
lastDayHeld, and ask the seller for its delivery rather than reporting a drop. - Zero is not stale. A buy whose seller reported zero delivery on every
day through its
dueThroughis current, and its zeros are real. - A buy whose flight has ended can still be stale. If its delivery stopped before the flight ended, the missing days stay overdue. A buy whose delivery runs to its flight end is not stale.
- A gap followed by later delivery does not make a buy stale. Only the days after the last day held count.
asap counts from the day the buy was booked.
The other fields keep their meaning: a row’s dataThrough and finality still
come only from the seller’s reporting revision, and coverage still names
campaigns with no rows. deliveryFreshness is absent for synthetic demo data,
and when it could not be read; the text answer then says so, and the rows and
totals are returned as usual. It is also absent when more than 2,000 media buys
are in scope. The text answer then asks you to narrow the read with an
advertiser, campaign or media buy filter, or a shorter range.
For stored Buyer campaign delivery, totals covers every matched row, not just
the current page. Do not add the repeated totals from successive pages. Unless
you send currency, mixed currency results are not converted: monetary totals
can be unavailable while counts remain usable. Keep each row’s currency with its
monetary values. To read every row and the totals in one currency, see
Converting into one currency.
Conversions already applied
Stored Buyer campaign delivery reports each media buy’s spend in its advertiser’s currency. When a seller reports a buy’s spend in another currency, Apostra converts it before the rows are built, sospend, conversion_value
and the cost metrics on those rows are converted figures, not the numbers the
seller sent. The response states every conversion it applied in
currencyConversions:
- There is one entry for each media buy behind the page’s rows whose spend was
converted, ordered by
mediaBuyId. The field is absent when none was. fromCurrencyis the currency the spend was in before conversion: the currency the seller reported, or the currency the seller is paid in when the seller’s label disagrees with it.toCurrencyis the advertiser’s currency.rateis the number oftoCurrencyunits per onefromCurrencyunit.rateSourcesays where the rate came from:booked: the rate locked when the buy was booked.snapshot: Apostra’s daily rate store, for the day the buy was created, used for a buy booked without a locked rate.settlement: the seller labelled the spend with a currency it is not paid in. Apostra takes the spend in the currency the seller is paid in, which is the advertiser’s currency, at a rate of 1.fromCurrencyandtoCurrencyare then the same, andrateDateis null because no rate was looked up.
rateDateis the UTC date of the rate.- The list holds at most 100 entries. When more buys behind the page were
converted,
currencyConversionsOmittedgives the number left out; it is absent otherwise. Group bymedia_buyor narrow the filters to see each one. - The entries cover the buys behind this page’s rows, while
totalscovers every matched row, so a converted buy that appears only on a later page is in the totals but listed on that later page.
Converting into one currency
Sendcurrency with report: "campaign_delivery" to read money on every row
and on the totals in one currency:
currency is an uppercase ISO-4217 code, one of AUD, BRL, CAD, CHF, CNY, DKK,
EUR, GBP, HKD, IDR, INR, JPY, KRW, MXN, NOK, NZD, PLN, SEK, SGD, USD and ZAR:
the currencies Apostra’s daily rate store prices. Any other code is refused. It
applies to campaign_delivery only. live_campaign_delivery, seller
delivery and margin refuse it: the live report is the seller’s own payload,
and seller reports are not converted.
The conversion happens after conversions already applied,
so it starts from each row’s advertiser currency:
- Each day converts at that day’s rate. A row that spans several days,
because
dateis not one of its dimensions, is converted day by day and then added up. A range that spans a currency move therefore reads correctly. - Rates come from the daily rate store. It holds one rate per currency per UTC day against USD, and other pairs are crossed through USD. When a day has no rate, the most recent rate from up to 7 days before is used. Reading delivery never creates a rate.
- Counts do not change. Impressions, clicks, conversions and the other
counts are never converted.
cpm,cost_per_click,cost_per_acquisitionandroasare worked out again from the converted money. - A row with a day that has no rate is not converted. It keeps its own
currencyand values, so a row whosecurrencydiffers from the one you asked for was not converted.totalsthen reports money metrics as unavailable withreason: "fx_rate_unavailable"andcurrencyas null, rather than adding a partial sum. Counts still total. - Rows that differed only by currency become one row once both are converted.
- Goal progress is not converted.
goalProgressstays in each campaign’s own currency.
conversion:
rateBasisis alwaysdailyandrateSourceis alwayssnapshot, the daily rate store.carriedForwardDaysis the most days any rate used was carried forward from an earlier day, at most 7. It is 0 when every rate was the day’s own.unconvertedlists each source currency and day that had no rate, ordered by currency then date, at most 100.unconvertedOmittedgives the number left out and is absent otherwise. It covers every matched row, liketotals.
conversion is absent when you do not send currency, and the response is
then exactly what it is without the option. A nextCursor belongs to the query
that returned it, including its currency. If the rates cannot be read, the
call returns SERVICE_UNAVAILABLE; retry, or omit currency to read each row
in its own currency.
Converted figures are for reporting. Billing keeps the rate locked when a buy
was booked, so a converted spend can differ from what is invoiced.
Live Buyer campaign delivery does not come from Apostra’s reporting store and
does not claim reporting-pipeline finality. Keep the returned currency and any
unavailable values or warnings with the provider totals.
Delivery from Google Ad Manager sellers
Some sellers sell Google Ad Manager (GAM) inventory through a sales agent Apostra runs for them. Their products’reporting_capabilities declare an
expected_delay_minutes of at least 240 and list unfiltered_impressions from
google.com in vendor_metrics.
GAM impressions and clicks are filtered for invalid traffic
impressions and clicks from these sellers are GAM’s ad-server counts, after
GAM has removed the traffic it judged invalid. Google says Ad Manager “discards
impressions and clicks that are considered invalid”
(how Ad Manager counts impressions and clicks),
and that its metric totals are net of General Invalid Traffic (GIVT) filtration
and some Sophisticated Invalid Traffic (SIVT) filtering techniques
(Ad Manager’s invalid traffic methodology).
The seller also reports unfiltered_impressions and unfiltered_clicks, AdCP
vendor metrics from google.com. They are GAM’s counts before invalid-traffic
filtering, for comparison: the gap between the unfiltered and filtered counts
is the traffic GAM judged invalid. They are on each package’s
vendor_metric_values in the delivery payload of a live_campaign_delivery
read. Stored campaign_delivery rows carry the filtered counts only.
How often GAM delivery arrives
Delivery from these sellers comes in two forms: provisional figures within minutes, and daily figures once GAM has counted each day. Provisional figures, about every 15 minutes. While a buy runs, the seller’s agent re-reads its live GAM line items about every 15 minutes. Apostra reads the result from the agent every 5 minutes, as each package’s snapshot: impressions, clicks and spend since the flight started. So new figures reach you within about 5 minutes of the agent capturing them. A buy is read this way from the start of its flight for as long as the seller reports it active. You see these figures in Campaign Pulse, labelled provisional. They are not final and not billable, and they are kept apart from the delivery reads on this page:campaign_delivery rows and
live_campaign_delivery reads never include them. The provisional and daily
figures come from different GAM reads, and GAM can still revise its counts, so
the daily figures for a day can differ from the provisional ones you saw during
it.
Daily figures, twice a day. GAM needs about four hours to count delivery,
and these products report daily in the network’s timezone
(reporting_capabilities.timezone). Apostra reads each live buy from the seller
twice a day, at 02:00 and 14:00 UTC. It reads more often until a buy’s first
figures arrive, and keeps reading twice a day for seven days after the buy ends,
to pick up GAM’s revisions.
So a day’s figures fill in over the reads during and after it, about four hours
behind GAM. How long before you see the whole day depends on the network’s
timezone: the day is whole at the first read at least four hours after it ends.
For a network in the Americas or Europe, that is usually the 14:00 UTC read the
next day. For one in Asia or Australia, it is the 02:00 UTC read the next day.
A live_campaign_delivery read asks the seller when you call, and its agent
runs a new GAM report each time, so it can include hours the last scheduled
read did not. It is still about four hours behind GAM.
Campaign Pulse uses the declared
delay to work out when a report is due.
Rating points
Sellers of linear TV and radio usually price in rating points (AdCP’scpp,
cost per point) and report the points they delivered as grps. Rating points
are measured against the demographic named in the package’s cost-per-point
pricing, so points from different packages cannot be added up.
- Where it is available. Request
grpson acampaign_deliveryread withmedia_buyorpackageindimensions. Without either, the request is refused. Other reports do not accept it. - One package at a time. A row’s value is the sum of one package’s points
over the days in the row. A media buy row has a value only when a single one
of its packages reported points. Otherwise, and in
totalswhen more than one package reported points,grpsreadsnot_additive. - Absent is not zero. A day without points adds nothing. A row with no
points at all reads
missing. - Read the basis with the number. Broadcast ratings mature: a seller may
first report live or C3 points and replace them with C7 points a week or two
later. An available value carries
basis:measurement_window(for examplec3orc7) andis_final.is_finalistrueonly when the seller called every day behind the value final.falsemeans a figure that can still change. A field is left out when it is not known for every day, or, for the window, when the days name different windows. Points stored before 9 November 2026 have no basis.
Reach and frequency
Reach counts unique people, households or devices, so it cannot be added up the way impressions can. Apostra reports the reach a seller sent and never works one out.- Where it is available.
live_campaign_deliveryreturnsreach,frequency,reach_unitandreach_windowas the seller reported them, on the media buytotalsand on each package inby_package. The same values are in thedeliverypayload and indeliverySummary. Storedcampaign_deliveryand sellerdeliveryreads return them when you request thereachandfrequencymetrics, with the unit and window on each value and the one-row rule below. - Absent is not zero. A seller that sent no reach leaves the fields out. Do
not read a missing
reachorfrequencyas0. - Read the unit and the window with the number.
reach_unitsays what is counted:individuals,households,devices,accounts,cookiesorcustom. Compare reach only between values with the same unit.reach_windowsays what period the number covers:cumulativeis everyone since the campaign started,periodis one non-overlapping period such as a single day, androllingis a trailing period ending at the report.periodandrollingcarry the length inreach_window.period. A value with noreach_windowhas an unspecified window. - Never add reach up. Do not sum
reachacross days, packages or media buys. The same person appears in many of them, so a sum counts people more than once. Acumulativevalue replaces the earlier one, and arollingvalue stands on its own. Do not averagefrequencyacross rows either. - A buy-level value and a package value are separate reports. A seller may report reach for the whole media buy and for each package. The package values do not add up to the media buy’s reach.
- Stored reads return a value only from one stored row. A row’s
reachorfrequencyis returned only when exactly one stored report row behind it carries one. It comes back withreach_unitandreach_windowon the value, each left out when the seller sent none. When two or more rows carry reach (different days, packages or sources), the metric readsnot_additive, intotalsas well, and when none does it readsmissing. Nothing is summed or chosen from several. Several reports of one media buy, package and day are merged into one row that carries none, so that row readsmissing. - Which row that is depends on the grain. A stored row is a media buy and
day, or a package and day. A day the seller broke out by package is read from
its package rows, so a package’s reach appears on its package row, and a media
buy’s own reach stored beside them is not returned by
campaign_delivery(read it live withlive_campaign_delivery). On a media buy row or intotals, a value appears only if exactly one of those rows carries reach, so a buy whose packages each report reach has none at the media buy level. Sellers that declare a window on a multi-day report have its reach stored once, on the last day the report covers: a row that spans the report shows it, and a row for one earlier day does not. Readreach_windowbefore you read the number: a one-dayperiodwindow on a week-long row is one day’s reach.
4. Run a repeatable extraction job
For a daily dashboard or warehouse load, your worker can:- Load the account, report, requested dimensions, and last completed date window from its checkpoint.
- Read each bounded window and all its pages into a staging destination.
- Check warnings and coverage, then publish the completed window. Use a key containing its account, dimensions, date, and currency so a retry replaces the same data rather than appending duplicates.
- Advance the checkpoint only after the destination has accepted the complete window.
- Re-read a recent overlap window according to your source’s correction and freshness needs. Retain when each extract was observed.
Historical delivery unavailable
An Apostra storefront’sget_media_buy_delivery response can include
HISTORICAL_DELIVERY_UNAVAILABLE in its errors when an ad platform rejects
a historical day’s delivery request as invalid. The error message names the
affected date. Delivery totals can be incomplete for that day; the confirmed
delivery checkpoint does not advance past the gap. Treat the affected reporting
window as incomplete and contact support with the media buy ID and date.
For an active route, Apostra makes up to three attempts for a non-transient
invalid request, with backoff between attempts. If the route is ending, its
final historical read is the last attempt. Transient failures, including rate limits and server errors,
continue to retry under the usual policy.
5. Choose CSV export or scheduled cloud delivery
For a CSV aggregate, use the v2 REST reporting contract:downloadUrl, expiresAt, fileName, and
rowCount. Fetch the file in the consuming service; the signed URL is a bearer
credential and must not appear in logs or public dashboards. See
CSV export.
This v2 buyer reporting endpoint is deprecated for external callers and switches
off on 1 December 2026; existing integrations are grandfathered until then. New
and migrating integrations move to the V3 reporting tools — see
Move a v2 buyer REST integration to V3.