Get reporting metrics

GET /api/v2/buyer/reporting/metrics Returns delivery metrics rolled up across the advertiser → campaign → media buy → package tree. Choose a hierarchical summary or flat timeseries view, scope with advertiserId, campaignId, channelGroupId, or mediaBuyId, and set the window with days or an explicit startDate/endDate. This endpoint is day-grain only — for hourly counts use Get event summary.

Request

curl "https://api.apostra.com/api/v2/buyer/reporting/metrics?days=14&advertiserId=42&demo=false" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

curl "https://api.apostra.com/api/v2/buyer/reporting/metrics?view=timeseries&days=90&download=true&demo=false" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Parameters

Param	Type	Required	Notes
`advertiserId`	string	No	Filter to one advertiser
`campaignId`	string	No	Filter to one campaign. Must belong to `advertiserId` if both are passed
`channelGroupId`	string	No	Filter to media buys in one saved campaign channel group. Combine with `advertiserId` or `campaignId` to narrow to their intersection
`mediaBuyId`	string	No	Filter to one media buy owned by the authenticated Buyer
`startDate`	string	No	`YYYY-MM-DD`. Overrides the `days` window when set
`endDate`	string	No	`YYYY-MM-DD`. Defaults to today
`days`	integer	No	`0`–`90`, default `7`. Use `0` for the full campaign timeframe
`view`	enum	No	`summary` (default) or `timeseries`
`download`	boolean	No	Default `false`. When `true`, returns a signed CSV URL instead of JSON
`demo`	boolean	No	Default `false`. When `true`, returns auto-generated demo data instead of real data

Response

The example below uses illustrative, non-zero conversionValue, cpa, and roas values to show the response shape. See the note below the response for how these fields behave when a seller has not reported conversion data.

{
  "advertisers": [
    {
      "advertiserId": "42",
      "advertiserName": "Northwind Outdoors",
      "metrics": { "impressions": 12345, "spend": 678.9, "clicks": 210, "views": 9800, "completedViews": 4200, "conversions": 18, "leads": 3, "videoCompletions": 4200, "conversionValue": 950.0, "ecpm": 55.0, "cpc": 3.23, "ctr": 0.017, "completionRate": 0.43, "cpa": 37.72, "roas": 1.4 },
      "campaigns": [
        {
          "campaignId": "cmp_001",
          "campaignName": "Spring Trail Series",
          "management": "managed",
          "metrics": { "impressions": 12345, "spend": 678.9, "clicks": 210, "views": 9800, "completedViews": 4200, "conversions": 18, "leads": 3, "videoCompletions": 4200, "conversionValue": 950.0, "ecpm": 55.0, "cpc": 3.23, "ctr": 0.017, "completionRate": 0.43, "cpa": 37.72, "roas": 1.4 },
          "mediaBuys": []
        }
      ]
    }
  ],
  "totals": { "impressions": 12345, "spend": 678.9, "clicks": 210, "views": 9800, "completedViews": 4200, "conversions": 18, "leads": 3, "videoCompletions": 4200, "conversionValue": 950.0, "ecpm": 55.0, "cpc": 3.23, "ctr": 0.017, "completionRate": 0.43, "cpa": 37.72, "roas": 1.4 },
  "periodStart": "2026-05-24",
  "periodEnd": "2026-06-06"
}

Each campaign block (and each timeseries row) carries a management state: tracked (a campaign you did not set up through the platform, mirrored read-only from a connected provider account) or managed (authored or adopted through the platform). This surface currently reports managed campaigns only — tracked mirror delivery is excluded — so totals never silently mix the two states. conversionValue is advertiser-attributed revenue from conversions; unlike spend, it is never grossed up with platform fees. cpa (spend / conversions) is null when there are no conversions. roas (conversionValue / spend) is null when spend is zero, or when there is no conversion signal at all — zero conversions and zero attributed value; it reports a true 0 only when conversions are real but their attributed value is zero. These fields depend on the seller reporting conversion data. Where a seller reports none, conversionValue is 0 and cpa and roas are null.

Goal progress

Every media buy block, and every campaign block, that has something to judge against carries goalProgress: delivery compared with the buyer’s goal and the seller’s commitment. A media buy is judged against its own goal commitment; a campaign against its primary goal, with the weakest commitment across its buys. The campaign’s answeredTarget is likewise the weakest answer: the highest cost per unit, or the lowest rate or return. It is null when the buys answered in different kinds. Blocks with neither a goal nor a commitment omit the field. The timeseries view carries the same judgements, over the whole period, in a goalProgress object with mediaBuys[] and campaigns[]. What each part means and how to read it is explained in Goal-seeking campaigns. The rows below give the media buy block’s path; the campaign block carries the same object at advertisers[].campaigns[].goalProgress.

Field	Type	Notes
`advertisers[].campaigns[].mediaBuys[].goalProgress.goal`	object or null	The ask being judged: `kind` (`metric` or `event`), `subject` (the metric name, or the event types joined with `\|`), `eventTypes`, and the `target` the buyer stated. Null when only a fixed outcome price is on record.
`advertisers[].campaigns[].mediaBuys[].goalProgress.askedTarget`	object or null	The buyer’s target: `cost_per`, `threshold_rate`, or `per_ad_spend` with a `value`, or `maximize_value`.
`advertisers[].campaigns[].mediaBuys[].goalProgress.answeredTarget`	object or null	The cost or return the seller’s terms commit or aim at, from the media buy’s goal commitment.
`advertisers[].campaigns[].mediaBuys[].goalProgress.commitment`	string or null	`guaranteed`, `best_effort`, or `report_only`. At campaign level, the weakest across the campaign’s buys; a buy with no commitment counts as `report_only`.
`advertisers[].campaigns[].mediaBuys[].goalProgress.commitmentSource`	string or null	`proposal` or `campaign` on a media buy; null at campaign level.
`advertisers[].campaigns[].mediaBuys[].goalProgress.actual`	object or null	The achieved value for the goal’s metric, from the same delivery this response reports: `kind` (`cost_per`: spend ÷ units, per thousand for impressions; `threshold_rate`: units ÷ `denominatorUnits`; `volume` when there is no numeric target), `value`, `unit`, `units` (the delivered count), `denominatorUnits` (what a rate divided by — measurable impressions for a `viewable_rate` goal, impressions for every other rate; null for a cost or a volume), `perUnits` (1,000 for impressions, 1 otherwise), and `currency` for a cost. Uses this surface’s denomination, so a buyer’s actual cost per click is fee-inclusive like `cpc`. Null when the metric was not reported.
`advertisers[].campaigns[].mediaBuys[].goalProgress.verdict`	string or null	`on_track`, `behind`, or `beat`. Cost targets are lower-is-better; rates and returns higher-is-better. `beat` means at least 10% better than the target. Null whenever the evidence does not support a verdict.
`advertisers[].campaigns[].mediaBuys[].goalProgress.judgedAgainst`	string or null	`asked` when the verdict compares with your target, `answered` when you stated no target and the seller’s price is the yardstick.
`advertisers[].campaigns[].mediaBuys[].goalProgress.verdictWithheld`	string or null	Why there is no verdict: `no_goal`, `no_target`, `metric_unsupported`, `metric_not_reported` (no delivery in the period, or the seller never reported a value for the goal’s metric, or the seller’s reporting commitments leave it out, or the seller reported the units but not what they divide by: spend for a cost-per target, measurable impressions for a `viewable_rate` target, impressions for every other rate target), or `too_few_observations`. A cost or a volume needs at least 100 clicks or completed views, 1,000 impressions, views or viewable impressions, or 20 leads. A rate is judged on what it divided by instead, and needs at least 1,000 measurable impressions or impressions — so a low rate over a large, well-measured population is a real verdict even when its own count is small. `metric_unsupported` covers metrics delivery does not carry (such as `reach`), event goals other than lead-only ones, a fixed price on an outcome delivery cannot count (`cpa`, `vcpm`, `cpp`) when the campaign states no goal, and return-on-ad-spend targets: delivery reports one conversion count and one conversion value with no event type, so judging a purchase goal on them would credit it with other events, and that read waits for event-scoped counts. A withheld verdict is not a bad verdict.
`advertisers[].campaigns[].mediaBuys[].goalProgress.basis`	object or null	Who counted the number. Delivery here is what the seller reported, so `kind` is `seller_attested`.
`advertisers[].campaigns[].mediaBuys[].goalProgress.freshness`	object	`dataThrough` (last date with delivery in the period), the seller’s last stated `reportingPeriodEnd`, `nextExpectedAt`, `notificationType` and `sequenceNumber`, `awaitingLaterReport` (the seller has signalled a later report will supersede this one), and `missingMetrics` (the goal’s metric when nothing was reported, plus any metric the seller committed to report that this surface does not carry).
`advertisers[].campaigns[].mediaBuys[].goalProgress.pace`	object or null	Spend measured against the flight — see Spend pace below. Media buy blocks only; campaign blocks carry `null`.

A media buy committed at 3.00 per click that has delivered 500 clicks for 2,000 reads actual: { kind: "cost_per", value: 4, unit: "clicks", units: 500 } and verdict: "behind". The same buy on its first day with two clicks reads the actual and verdictWithheld: "too_few_observations", with no verdict.

A viewable_rate goal is judged only from the viewable and measurable impression counts in the AdCP viewability object. Reporting does not read that object yet, so a viewable_rate goal currently reads verdictWithheld: "metric_not_reported" with viewability in missingMetrics. The views metric is content views — the quantity CPV pricing bills on — and is never used as a stand-in for viewable impressions.

Spend pace

goalProgress.pace answers a separate question from the goal: is the money moving at the rate the flight implies? “Spend 200 a day at 80% viewable” is two answers, not one — the pace verdict and the goal verdict are reported side by side. Pace is not spend ÷ budget: a buy three days into a thirty-day flight that has spent a tenth of its budget is exactly on pace, while a buy on its last day that has spent the same tenth is nine tenths undelivered.

Field	Type	Notes
`advertisers[].campaigns[].mediaBuys[].goalProgress.pace.flightElapsed`	number or null	Fraction of the whole flight elapsed, 0 to 1. Measured to the end of the last reporting day with delivery, not to now, so a seller who reports a day in arrears does not read as a day behind. A buy booked `asap` is measured from when it was created. This tells you where the buy is in its life; it is not what the expectation below is measured over.
`advertisers[].campaigns[].mediaBuys[].goalProgress.pace.measuredFraction`	number or null	Fraction of the flight the reported spend actually covers — the window you asked for, clipped to the flight. Equal to `flightElapsed` on a lifetime read, smaller on a windowed one.
`advertisers[].campaigns[].mediaBuys[].goalProgress.pace.expectedSpend`	number or null	`budget × measuredFraction` — what an even pace across the flight expects over that same stretch.
`advertisers[].campaigns[].mediaBuys[].goalProgress.pace.actualSpend`	number or null	Delivered spend, in the same denomination as the budget (gross, fee-inclusive, like `spend`).
`advertisers[].campaigns[].mediaBuys[].goalProgress.pace.ratio`	number or null	`actualSpend ÷ expectedSpend`. 1 is exactly on the even-pace line.
`advertisers[].campaigns[].mediaBuys[].goalProgress.pace.spendPerDay`	number or null	Delivered spend per day of the measured interval. A buy still delivering past its booked end counts the days it actually ran.
`advertisers[].campaigns[].mediaBuys[].goalProgress.pace.budgetPerDay`	number or null	The even-pace daily rate the budget and flight imply — compare it with `spendPerDay` to read a “200 a day” ask.
`advertisers[].campaigns[].mediaBuys[].goalProgress.pace.currency`	string or null	Denomination of the money fields.
`advertisers[].campaigns[].mediaBuys[].goalProgress.pace.verdict`	string or null	`on_pace` within 10% of the even-pace line, `behind` under it, `ahead` over it. `ahead` is neither praise nor alarm: at this rate the flight exhausts early.
`advertisers[].campaigns[].mediaBuys[].goalProgress.pace.verdictWithheld`	string or null	Why there is no pace verdict: `no_budget`, `no_flight` (no start or end recorded), `flight_not_started`, `window_outside_flight` (the window you asked for covers none of the flight — a recent window of a flight that ended months ago), `too_short_a_window` (the reported spend covers under 5% of the flight, where one late report swings the ratio by multiples), or `spend_not_reported`. The facts already known — elapsed flight, expected spend, budget per day — are still reported.

Pace is always measured over the window you asked for. Narrow days and both actualSpend and expectedSpend shrink together, so the verdict stays comparable; it never compares a week of spend with a month of expectation.

When download=true, the response is instead { downloadUrl, expiresAt, fileName, rowCount } with a signed URL that expires in 7 days. Treat that URL as a bearer credential.

Channel-group lineage

When a campaign uses channel groups, reporting carries the group that compiled into each media buy:

A summary response returns advertisers[].campaigns[].mediaBuys[].channelGroup as { channelGroupId, name }.
A timeseries response returns channelGroupId and channelGroupName on every row.
A CSV export appends Channel Group ID and Channel Group Name columns.

Legacy or ungrouped media buys return channelGroup: null in a summary, channelGroupId: null and channelGroupName: null in time-series JSON, and blank CSV fields. These values are saved media-buy lineage; Interchange does not infer them from names, products, or delivery. This REST endpoint accepts channelGroupId as a scope filter, but it does not group rows by that field. For an agent-side rollup, call V3 get_delivery with report: "campaign_delivery", dimensions: ["channel_group"], and, when you need one group, filters.channelGroupId. Rows then return the selected dimension as channelGroup: { id, name }, or null for an ungrouped buy. When you pass filters.mediaBuyId, get_delivery returns delivery for that media buy only; it does not include other media buys from the same storefront.

Errors

400 VALIDATION_ERROR — malformed startDate/endDate, days outside 0–90, or a campaignId that does not belong to the given advertiserId.
422 SPEND_DENOMINATION_UNRESOLVED — one or more media buys in scope have spend that cannot be denominated, so no figure would be correct. The error names them in its message and in details.mediaBuyIds, alongside details.unresolvedCount. Classified terminal — do not retry. The cause is delivery data that is wrong at rest (a source reporting a currency it is not paid in, a buy missing its cross-currency booking evidence, or currencies mixed within the period), so every retry reproduces it. Report the named ids to support; to keep reporting in the meantime, scope the request to exclude them (a single campaign, or a period they did not deliver in). Unaffected buys report normally, and view=timeseries can still return rows for buys whose days each carry their own currency.
503 FX_RATE_UNAVAILABLE — the exchange-rate feed could not price a currency pair. Classified transient; retry shortly.

See Errors for the full error contract, and Cross-currency for how delivery spend is denominated.

Reporting tasks

All reporting operations

Reporting overview guide

Hierarchy, metrics, CSV export, delivery flow

Get event summary

Hourly event counts by type

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

Get reporting metrics

Request

Parameters

Response

Goal progress

Spend pace

Channel-group lineage

Errors

Reporting tasks

Reporting overview guide

Get event summary

​Request

​Parameters

​Response

​Goal progress

​Spend pace

​Channel-group lineage

​Errors

​Related

Reporting tasks

Reporting overview guide

Get event summary

Request

Parameters

Response

Goal progress

Spend pace

Channel-group lineage

Errors

Related