Aggregate Report

Returns metrics grouped by the dimensions you choose — like a pivot table over your impression data. Use it for daily revenue summaries, per-ad-unit fill rates, or country/format breakdowns without pulling raw impressions.

POST /reporting/v1/publisher/aggregate
Authorization: Bearer <your-reporting-key>
Content-Type: application/json

Request Body

Field	Type	Default	Description
publisher_id	string	required	Your publisher ID.
date_range	object	required	{ "start", "end" } — ISO 8601 UTC datetimes or bare dates (e.g. 2026-07-06), inclusive; max span 31 days. A bare start expands to 00:00:00 and a bare end to 23:59:59 UTC, so { "start": "2026-07-06", "end": "2026-07-06" } covers the full day.
metrics	string[]	required	Metrics to compute. See Metrics.
dimensions	string[]	[]	Dimensions to group by. See Dimensions. Omit to get a single grand-total row.
dimension_filters	object[]	[]	Row filters, e.g. { "dimension": "COUNTRY", "values": ["US", "GB"] }. Filters combine with AND across dimensions, OR within values.
sort_order	string	asc	asc or desc, sorted by the requested dimensions in order.
limit	int	1000	Page size, max 5000.
cursor	string	—	Pagination cursor from a prior response. See Pagination.

Dimensions

Dimension	Row value	Description
DATE	"2026-07-14"	UTC calendar day.
AD_UNIT_ID	"SIM-RWD-A3F9K2BX"	Ad unit ID.
AD_UNIT_NAME	"Daily Reward Video"	Ad unit name, as set in the dashboard. Filter values are case-insensitive
AD_FORMAT	"rewarded"	rewarded, interstitial, or native.
COUNTRY	"US"	ISO 3166-1 alpha-2.
OS	"ios"	ios or android.
STATUS	"final"	estimated or final. See Estimated vs. final revenue.

Any dimension you omit is summed across. Response rows include only the dimensions and metrics you requested.

Metrics

Metrics follow the delivery funnel: requested → served → shown.

Metric	Type	Definition
REQUESTS	int	Ad requests: SERVED + no-fills.
SERVED	int	Ads returned to the app, whether or not they were later displayed.
FILL_RATE	number	SERVED / REQUESTS, from 0 to 1. null when there are no requests.
IMPRESSIONS	int	Ads actually displayed to the user.
SHOW_RATE	number	IMPRESSIONS / SERVED, from 0 to 1. null when nothing was served.
CLICKS	int	Ad clicks.
REVENUE	number	Your revenue in USD. Earned on impressions — served-but-never-shown ads contribute nothing.
AVG_CPM	number	Blended eCPM: REVENUE × 1000 / IMPRESSIONS. null when there are no impressions.

Example: Daily Revenue Summary

{
  "publisher_id": "pub_0a1b2c3d",
  "date_range": { "start": "2026-07-14", "end": "2026-07-20" },
  "dimensions": ["DATE"],
  "metrics": ["REVENUE", "IMPRESSIONS", "AVG_CPM"]
}

{
  "rows": [
    { "date": "2026-07-14", "metrics": { "revenue": 482.0, "impressions": 40000, "avg_cpm": 12.05 } },
    { "date": "2026-07-15", "metrics": { "revenue": 558.9, "impressions": 45000, "avg_cpm": 12.42 } }
  ],
  "pagination": { "next_cursor": null, "has_more": false }
}

Example: Revenue by Country and Format

{
  "publisher_id": "pub_0a1b2c3d",
  "date_range": { "start": "2026-07-14", "end": "2026-07-20" },
  "dimensions": ["COUNTRY", "AD_FORMAT"],
  "metrics": ["REVENUE", "IMPRESSIONS"],
  "dimension_filters": [
    { "dimension": "COUNTRY", "values": ["US", "GB"] }
  ],
  "sort_order": "desc"
}

{
  "rows": [
    { "country": "US", "ad_format": "rewarded", "metrics": { "revenue": 322.14, "impressions": 18200 } },
    { "country": "US", "ad_format": "interstitial", "metrics": { "revenue": 96.35, "impressions": 9400 } },
    { "country": "GB", "ad_format": "rewarded", "metrics": { "revenue": 51.66, "impressions": 4100 } }
  ],
  "pagination": { "next_cursor": null, "has_more": false }
}

Example: Delivery Funnel by Ad Unit

{
  "publisher_id": "pub_0a1b2c3d",
  "date_range": { "start": "2026-07-14", "end": "2026-07-20" },
  "dimensions": ["AD_UNIT_ID"],
  "metrics": ["REQUESTS", "SERVED", "FILL_RATE", "IMPRESSIONS", "SHOW_RATE"]
}

{
  "rows": [
    { "ad_unit_id": "SIM-INT-77Q4MNPC", "ad_unit_name": "Chat Interstitial", "metrics": { "requests": 30000, "served": 26400, "fill_rate": 0.88, "impressions": 23760, "show_rate": 0.9 } },
    { "ad_unit_id": "SIM-RWD-A3F9K2BX", "ad_unit_name": "Daily Reward Video", "metrics": { "requests": 52000, "served": 40560, "fill_rate": 0.78, "impressions": 34476, "show_rate": 0.85 } }
  ],
  "pagination": { "next_cursor": null, "has_more": false }
}

Reconciling estimated and final revenue

Group by STATUS (or filter to final) when reconciling payouts. If you group by STATUS, a dimension key's final row supersedes its estimated row as settlement completes (7 days after serve) — overwrite by key when syncing, don't append.