The calls, side by side
Every V3 call is a
POST to https://api.apostra.com/api/v3/tools/<operation>
with your key as a bearer token. A key that belongs to one account needs no
other header. See Make a request.
Read advertisers
data.objects.results, one object per advertiser with
advertiserId, name, primaryCurrency and status. To read one advertiser,
call get with kind: "advertiser" and its id; the advertiser is in
data.object.
Read an advertiser’s campaigns
data.objects.results[].campaign.campaignId and
data.objects.results[].advertiser.advertiserId. Filters always go inside
filter; V3 HTTP does not read a filter from the top level of the body.
Page through results
v2 paged with numbers (limit and offset for advertisers, take and skip
for campaigns). V3 pages with a cursor:
- Send
limit(up to 200 forsearch, up to 100 rows forget_delivery). - If the response has a
nextCursor(data.objects.nextCursorforsearch,data.page.nextCursorforget_delivery), send the same request again withcursorset to it. - Stop when the response has no
nextCursor.
limit.
Read delivery
v2GET /api/v2/buyer/reporting/metrics becomes get_delivery with
report: "campaign_delivery". For one advertiser and one day:
- Dates. Send
range.startDateandrange.endDate(up to 90 days), orrange.lifetime: true. There is nodaysparameter. - Grouping.
dimensionschooses the grouping, fromdate,advertiser,campaign,media_buy,packageand others. Each row carries its dimension values inrows[].dimensions, for examplerows[].dimensions.campaign.id. - Metric values. Each metric is an object, not a bare number:
{"value": 1250, "status": "available"}. Whenstatusisunavailable,valueisnullandreasonsays why. A missing value is never reported as zero. - Totals.
data.totals.metricsholds the total for each metric. When the matched delivery mixes provisional (Snapshot) and final (Official) figures,totalsgives no number andtotalsByFinalitygives one total per class. See Reporting for what each label means. - Paging. Rows come in pages of up to 100 (
limit); followdata.page.nextCursoras above.
Metric names
V3 uses AdCP’s delivery metric names.The v2 summary view
v2 reporting returns a tree by default (view=summary): advertiser, then
campaign, media buy and package, with totals at each level. get_delivery
returns flat rows instead. To build the same tree, request
dimensions: ["campaign", "media_buy", "package"] and group the rows in your
client. For daily rows, add date.
v2’s packageId and sellerPackageId are on each row’s package:
rows[].dimensions.package.id and rows[].dimensions.package.sellerPackageId.
If you join site sessions to delivery on the seller’s package id, the join
works the same way. See
Join package rows to your own data.
Goal progress comes back with report: "campaign_delivery" in
data.goalProgress: for each campaign and media buy in the page, its goal, the
actual result so far, and a verdict where the evidence supports one. It does
not include the v2 pace figures.
Goal shape in get_delivery
The V3 get_delivery goal is the same native AdCP optimization_goal shape as
the V3 campaign or media-buy progress include. Its assessment stays bounded
to the requested reporting range. Apostra returns it only while the current
campaign goal exactly matches the stored progress row. goal is null when the
campaign goal changed or was removed, the stored row differs, or a media buy’s
stored ask does not identify exactly one current campaign goal. Read AdCP’s
snake_case fields such as event_sources, event_source_id, and metric_id
directly. Do not read the former compact reporting fields such as subject,
eventTypes, or metricId; V3 does not reconstruct them from reporting. The
v2 REST goal shape is unchanged.
v2 put the currency conversion applied to a media buy’s spend on the buy, as
deliveryFxConversion. V3 lists the same conversions for the page in
data.currencyConversions, one entry per converted media buy:
See Conversions already applied.
v2’s
displayCurrency becomes currency on get_delivery with
report: "campaign_delivery". It converts the money on every row and on
totals, and the response describes the conversion in data.conversion:
One difference changes the numbers. v2 converts the whole window at one rate,
the rate of a single day. V3 converts each day at that day’s own rate, so a
range that spans a currency move gives a different, more accurate total. V3
also has no default: send
currency to convert. See
Converting into one currency.
These v2 reporting features have no V3 equivalent today: outcome counts from
your measurement uploads (outcomeType) and CSV download (download=true).
If you depend on one of them, tell us before you move.
Errors
V3 returns a non-2xx status with an AdCP error inerror; data is null.
- A request body that does not match the operation’s schema returns
422with codeINVALID_REQUEST, anderror.details.validationnames the field. v2 returned400for invalid query parameters. - A key cannot reach another account. Sending an
X-SCOPE3-CUSTOMER-IDheader that does not match the key’s account returns403.