Get reporting metrics

Deprecated. This page documents the v2 buyer API, which is closed to new API clients and switches off on 1 December 2026. Use V3 instead: see Move a v2 buyer REST integration to V3. The conversion endpoint, Log event, stays open.

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`
`outcomeType`	string	No	Timeseries only. Adds each row’s count of this outcome from your uploaded measurement records, and the cost per outcome. See Cost per outcome
`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, "viewability": { "viewable_impressions": 8100, "measurable_impressions": 11200, "viewable_rate": 0.723 } },
      "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, "viewability": { "viewable_impressions": 8100, "measurable_impressions": 11200, "viewable_rate": 0.723 } },
          "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, "viewability": { "viewable_impressions": 8100, "measurable_impressions": 11200, "viewable_rate": 0.723 } },
  "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. viewability contains the seller-reported viewable_impressions and measurable_impressions counts. Its viewable_rate is viewable_impressions / measurable_impressions. See Viewability for which reports count. The object is null, never a zero-filled object, when no report in scope measured viewability. views is a different metric: it counts content views, not viewable impressions. A CSV export carries Viewable Impressions, Measurable Impressions, and Viewable Rate after Channel Group Name.

Joining packages to your own data

A package has two ids. packageId is Apostra’s id for it. sellerPackageId is the seller’s own id for the same package. A {PACKAGE_ID} macro on your landing pages or trackers can arrive with either one, depending on how the seller served the ad. When one creative serves several packages, the seller fills it with its own id. To join site sessions or conversions to delivery by package, match the id your URL carries against packageId or sellerPackageId.

Field	Type	Notes
`advertisers[].campaigns[].mediaBuys[].packages[].sellerPackageId`	string or null	The seller’s own id for this package. Equals `packageId` when the package is booked on an inventory source Apostra runs, because Apostra is then the seller. `null` when a third-party seller’s own id is not known; Apostra never reports its own id in place of a third-party seller’s.
`timeseries[].sellerPackageId`	string or null	The same id on a timeseries row. `null` on a row with no package (`packageId: ""`).

A CSV export carries it as its last column, Seller Package ID, which is empty when the id is not known.

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`. For a vendor-measured goal with a rate target, `unit` is `vendorMetric`: `value` is the vendor’s value per measured impression, and `units` and `denominatorUnits` are the impressions the vendor measured. 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. For a vendor-measured goal, `metric_not_reported` means no seller reported the vendor’s value for the goal’s vendor and metric in the period, and `metric_unsupported` covers a cost target (the vendor defines the unit), values reported under more than one AdCP qualifier, and reports whose windows overlap without one containing the other. A withheld verdict is not a bad verdict.
`advertisers[].campaigns[].mediaBuys[].goalProgress.basis`	object or null	Who counted the number. `seller_attested`: the seller’s own delivery counts. `vendor_attested`: a measurement vendor’s values that sellers reported for a vendor-measured goal, with the `vendor`, its `metricId`, `measurableImpressions` (the impressions the vendor measured) and `coverage` (the share of delivered impressions it measured, 0 to 1, or null when delivery reported no impressions). `advertiser_measured`: your own measurement records for a vendor-measured goal, which take precedence, with the `vendor`, its `metricId` and `impressions` (delivered on the days your records cover).
`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`.

reportingPeriodEnd, nextExpectedAt, notificationType, and sequenceNumber come from the validated delivery-report envelope processed through either a reporting webhook or a storefront route poll. The API does not infer an omitted envelope value; when no processed envelope has supplied it, that field remains unavailable. A later report that omits an optional value does not clear a previously stored seller-stated value. 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.

Cost per outcome

Sellers’ conversions and cpa are empty when no seller reports conversions. To get the cost of an outcome you count yourself, such as a sign-up, upload your counts as measurement records that name the media buy and package, then read the timeseries with outcomeType:

curl "https://api.apostra.com/api/v2/buyer/reporting/metrics?view=timeseries&mediaBuyId=mb_123&startDate=2026-03-01&endDate=2026-03-31&outcomeType=signup" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

outcomeType needs campaignId or mediaBuyId, and startDate and endDate no more than 90 days apart. It cannot be combined with view=summary, download=true or demo=true. Each row then also carries:

Field	Type	Notes
`timeseries[].outcomeCount`	number or null	The count from your measurement records for this `outcomeType` whose window is this one day and that name this row’s media buy and package. On a row with no package (`packageId: ""`), records that name the media buy and no package. Records from different sources and geos are added together. `null` means no such record: not measured, which is different from a measured `0`.
`timeseries[].costPerOutcome`	number or null	`metrics.spend ÷ outcomeCount`, in the row’s `currency`. `null` when `outcomeCount` is `null` or `0`.
`timeseries[].outcomeSource`	string	Always `measurement_records`: the count is yours, never a seller’s `conversions`.

A record’s value counts the outcomes in its own window; it is never read as a running total. Only records whose window is a single day count, on that day. A record covering several days is not split across them and is not counted, so a weekly count added beside daily ones never counts the same days twice. Upload one record per package per day to read every day. Rows come from delivery: a package day with spend and no record reads outcomeCount: null, and a record for a day with no delivery has no row to appear on. Records that name only a campaign belong to no media buy and do not appear here.

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, a campaignId that does not belong to the given advertiserId, or outcomeType without the scope and dates Cost per outcome needs.
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

Joining packages to your own data

Goal progress

Spend pace

Cost per outcome

Channel-group lineage

Errors

Reporting tasks

Reporting overview guide

Get event summary

​Request

​Parameters

​Response

​Joining packages to your own data

​Goal progress

​Spend pace

​Cost per outcome

​Channel-group lineage

​Errors

​Related

Reporting tasks

Reporting overview guide

Get event summary

Request

Parameters

Response

Joining packages to your own data

Goal progress

Spend pace

Cost per outcome

Channel-group lineage

Errors

Related