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, 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.interchange.io/api/v2/buyer/reporting/metrics?days=14&advertiserId=42&demo=false" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

curl "https://api.interchange.io/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
`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. 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.

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

Errors

Reporting tasks

Reporting overview guide

Get event summary

​Request

​Parameters

​Response

​Errors

​Related

Reporting tasks

Reporting overview guide

Get event summary

Request

Parameters

Response

Errors

Related