Get reporting metrics

GET /api/v2/storefront/reporting/metrics Returns reporting metrics for every media buy the Merchandising Agent participates in through your storefront’s inventory sources. The storefront does not own these media buys — reporting is visible because the Merchandising Agent is the ADCP party to the transactions. The hierarchy is advertiser → media buy → package; there is no campaign level.

Request

curl

curl -G https://api.apostra.com/api/v2/storefront/reporting/metrics \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  --data-urlencode "view=summary" \
  --data-urlencode "startDate=2026-01-01" \
  --data-urlencode "endDate=2026-01-31" \
  --data-urlencode "mediaBuyId=mb_88421" \
  --data-urlencode "inventorySourceId=source_abc123"

Parameters

Field	Type	Required	Notes
`inventorySourceId`	string	No	Scope to one inventory source. Omit to include every source on the storefront
`mediaBuyId`	string	No	Scope to one Interchange media buy ID. Omit to include every media buy on the storefront
`startDate`	string	No	Start date, `YYYY-MM-DD`
`endDate`	string	No	End date, `YYYY-MM-DD`
`days`	integer	No	Days to include, `1`–`90` (default `7`). Used when explicit dates are omitted
`view`	enum	No	`summary` (hierarchical breakdown) or `timeseries` (flat per-day rows). Default `summary`
`download`	boolean	No	When true, returns a signed CSV download URL instead of JSON (default `false`)
`demo`	boolean	No	When true, returns auto-generated demo data (default `false`)
`sourceBreakdown`	boolean	No	Timeseries only. When true, returns one row per contributing inventory source. Default `false` preserves the legacy media-buy/package/date grain

Response

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

{
  "advertisers": [
    {
      "advertiserId": "5521",
      "advertiserName": "Contoso Outdoor",
      "metrics": {
        "impressions": 1284000,
        "spend": 9630.0,
        "clicks": 5136,
        "views": 1100000,
        "completedViews": 742000,
        "conversions": 318,
        "leads": 0,
        "videoCompletions": 742000,
        "conversionValue": 14200.0,
        "ecpm": 7.5,
        "cpc": 1.88,
        "ctr": 0.004,
        "completionRate": 0.675,
        "cpa": 30.28,
        "roas": 1.47
      },
      "mediaBuys": [
        {
          "mediaBuyId": "mb_88421",
          "name": "Q1 CTV Push",
          "status": "ACTIVE",
          "budget": 12000.0,
          "inventorySourceId": "source_abc123",
          "metrics": { "impressions": 1284000, "spend": 9630.0, "clicks": 5136, "views": 1100000, "completedViews": 742000, "conversions": 318, "leads": 0, "videoCompletions": 742000, "conversionValue": 14200.0, "ecpm": 7.5, "cpc": 1.88, "ctr": 0.004, "completionRate": 0.675, "cpa": 30.28, "roas": 1.47 },
          "packages": [
            {
              "packageId": "pkg_001",
              "productId": "prod_ctv_premium",
              "productName": "Premium CTV — Sports",
              "metrics": { "impressions": 1284000, "spend": 9630.0, "clicks": 5136, "views": 1100000, "completedViews": 742000, "conversions": 318, "leads": 0, "videoCompletions": 742000, "conversionValue": 14200.0, "ecpm": 7.5, "cpc": 1.88, "ctr": 0.004, "completionRate": 0.675, "cpa": 30.28, "roas": 1.47 }
            }
          ]
        }
      ]
    }
  ],
  "totals": { "impressions": 1284000, "spend": 9630.0, "clicks": 5136, "views": 1100000, "completedViews": 742000, "conversions": 318, "leads": 0, "videoCompletions": 742000, "conversionValue": 14200.0, "ecpm": 7.5, "cpc": 1.88, "ctr": 0.004, "completionRate": 0.675, "cpa": 30.28, "roas": 1.47 },
  "periodStart": "2026-01-01",
  "periodEnd": "2026-01-31"
}

Field	Type	Notes
`advertisers[]`	array	Advertiser-level breakdown
`advertisers[].metrics`	object	Reporting metrics for the advertiser (see below)
`advertisers[].mediaBuys[]`	array	Media-buy breakdown, each with `mediaBuyId`, `name`, `status`, `budget` (nullable), `inventorySourceId` (nullable), `metrics`, and `packages[]`
`advertisers[].mediaBuys[].packages[]`	array	Package breakdown with `packageId`, `productId`/`productName` (nullable), `metrics`
`totals`	object	Aggregated metrics across all advertisers
`periodStart` / `periodEnd`	string	Reporting window, `YYYY-MM-DD`

metrics carries raw counts (impressions, spend, clicks, views, completedViews, conversions, leads, videoCompletions, and conversionValue), calculated rates (ecpm, cpc, ctr, completionRate, cpa, and roas, each nullable when undefined), and a nullable AdCP-shaped viewability object. viewability contains viewable_impressions, measurable_impressions, and viewable_rate. conversionValue is the seller-reported revenue from conversions, always net (this surface never applies a buyer fee). 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. For view=timeseries, every row includes inventorySourceIds, the sorted, distinct source IDs carried by the delivery facts aggregated into that row. The existing inventorySourceId remains the deterministic legacy source. With sourceBreakdown=true, each row is source-grained, so inventorySourceId is the contributing source and inventorySourceIds contains that same single ID. These fields depend on the seller reporting conversion data. Where a seller reports none, conversionValue is 0 and cpa and roas are null. viewability comes from the viewability your inventory sources report. It is null, never a zero-filled object, when no report in scope measured viewability; see Viewability for which reports count. A CSV export appends Viewable Impressions, Measurable Impressions, and Viewable Rate as its last three columns.

Errors

400 VALIDATION_ERROR — malformed date, or days outside 1–90.
401 UNAUTHORIZED — missing or invalid API key.

See Errors for the full error contract.

Activity tasks

All activity operations

Inventory sources

Scope reporting by source

List activity

Configuration audit feed

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

Errors

Activity tasks

Inventory sources

List activity

​Request

​Parameters

​Response

​Errors

​Related

Activity tasks

Inventory sources

List activity

Request

Parameters

Response

Errors

Related