Reporting API

Build flat channel reports with selectable metrics, UTC time intervals, filters, and up to three breakdown columns. Authenticate with your management API key. Every request is scoped to your channel.

Two versions are available. V2 is the current version — one flexible report endpoint. V1 remains available for existing integrations.

Quickstart (V2)

Your first call in three steps:

1. Get your API key and metrics. Ask your Disco contact for a management API key and the metrics enabled for your channel. The same key works across the Channel API.
2. Choose the report shape. Select a UTC time grain, up to three breakdown columns, optional filters, and the metric columns you need. Import the V2 Postman collection or the V2 OpenAPI spec, or use curl. In Postman, set the api_key variable to your key.
3. Page through the rows. Read the complete filtered totals from summary and use pagination to retrieve every flat report row.

curl -G -H "x-api-key: your-management-api-key" \
  --data-urlencode "from=2026-07-18" \
  --data-urlencode "to=2026-07-20" \
  --data-urlencode "metrics=impressions,clicks,ctr" \
  "https://api.disconetwork.com/discobeat/reporting/v2/report/"

Authentication

Base URL: https://api.disconetwork.com

Pass your management API key in the x-api-key header. Contact your Disco representative to get a key. Every request is scoped to your channel by the key. Both versions accept GET only.

V2 — Build a report

GET /discobeat/reporting/v2/report/ — a complete filtered summary plus paginated, flat report rows. The response includes only the requested metrics and selected breakdown columns.

Parameter	Type	Required	Details
from	date	✓	Start date YYYY-MM-DD (UTC), inclusive.
to	date	✓	End date YYYY-MM-DD (UTC), inclusive. Max range 90 days.
metrics	list	✓	Comma-separated metrics enabled for your channel, e.g. impressions,clicks,ctr. Must be unique.
time_grain	string	–	UTC row interval: total, day, week, month, or hour. Default: total. Hour supports at most 3 days and one breakdown. Week and month edge periods are clipped to the requested range.
group_by	list	–	Comma-separated breakdown columns, up to three: publisher, page_type, widget_type, widget_id. Hourly reports support at most one.
publisher_ids	list	–	Comma-separated publisher UUID filter (max 250). Filtering does not add a report column.
page_types	list	–	Comma-separated page-type filter (max 250), e.g. ORDER_TRACKING,THANK_YOU.
widget_types	list	–	Comma-separated widget-type filter (max 250).
offset	integer	–	Pagination offset. Default: 0.
limit	integer	–	Page size, 1–250. Default: 50.

The response has four parts: data (flat rows — one per period × breakdown combination, each carrying period_start/period_end UTC boundaries, any breakdown columns, and the requested metrics), summary (the same metrics totalled across the complete filtered result, not just the page), pagination (offset, limit, total, has_more), and meta (timezone, data_through, request_id).

200 application/json (metrics=impressions,clicks,ctr · group_by=publisher,page_type · time_grain=day)

{
  "data": [
    {
      "period_start": "2026-07-18T00:00:00Z",
      "period_end": "2026-07-19T00:00:00Z",
      "publisher_id": "9aa17f8c-7746-4218-9025-83d38c406179",
      "publisher_name": "Acme Tracking Page",
      "page_type": "ORDER_TRACKING",
      "impressions": 225072,
      "clicks": 8928,
      "ctr": 0.0397
    }
  ],
  "summary": { "impressions": 450144, "clicks": 17856, "ctr": 0.0397 },
  "pagination": { "offset": 0, "limit": 50, "total": 36, "has_more": false },
  "meta": {
    "timezone": "UTC",
    "data_through": "2026-07-22T23:00:00Z",
    "request_id": "7e9fe348-7558-4e28-b8c6-b26ea44899eb"
  }
}

V2 limits

Interactive reports return at most 10,000 rows — narrow the date range or remove a breakdown if you exceed it. Requests must fit inside your channel's available data window; the error response returns the window when you miss it. meta.data_through tells you how fresh the data is.

Metrics reference

Metrics are enabled per channel — request only the ones enabled for yours (the METRIC_NOT_AVAILABLE error lists your allowed set).

Measured

Metric	Description
impressions	Brand ad displays
clicks	Brand ad clicks
conversions	Disco-attributed conversions
channel_payout	Your channel payout, USD
revenue_with_email	Net billable revenue from sessions with email
revenue_without_email	Net billable revenue from sessions without email
sessions	Distinct sessions with brand activity
feed_loads	Widget / feed loads

Calculated

Metric	Formula	Description
ctr	clicks / impressions	Click-through rate
cvr	conversions / clicks	Conversion rate
rps	channel_payout / sessions	Payout per session
rpl	channel_payout / feed_loads	Payout per feed load

note

Calculated ratios are rounded to four decimal places; a zero denominator returns 0. Conversions are Disco-attributed, so totals may differ from your own systems.

Errors

Status	Condition
400	Invalid query, a metric not enabled for your channel (METRIC_NOT_AVAILABLE), dates outside the available window (DATE_RANGE_OUTSIDE_AVAILABLE_WINDOW), range over 90 days, or a result over 10,000 rows (REPORT_ROW_LIMIT_EXCEEDED)
401	Missing or invalid management API key
405	Any method other than GET

A request with no data in the window returns 200 with zeroed metrics rather than an error.

V1 — for existing integrations

V1 has two fixed read-only endpoints and remains available. New integrations should use V2. In V1, pop-up (modal) placements are excluded from metrics.

Channel Summary

GET /discobeat/reporting/v1/summary/ — channel-level totals across all your publishers for a date range.

Parameter	Type	Required	Details
from	date	–	Start date YYYY-MM-DD (UTC), inclusive. Default: 6 days before to.
to	date	–	End date YYYY-MM-DD (UTC), inclusive. Default: today. Max range 90 days.

V1 responses split metrics into raw and calculated groups and include has_data, data_freshness (timestamp of the most recent data included), and generated_at (when the response was produced). When your channel has no data in the requested window, has_data is false and all metrics are 0.

200 application/json

{
  "channel_id": "7c3e1a90-4b2d-4f8a-9c11-2e6b5a0d8f34",
  "channel_name": "Acme",
  "date_range": { "from": "2026-06-08", "to": "2026-06-14" },
  "has_data": true,
  "metrics": {
    "raw": {
      "impressions": 480000, "clicks": 13440, "conversions": 672,
      "channel_payout": 9600.0, "revenue_with_email": 7200.0,
      "revenue_without_email": 2400.0, "sessions": 240000, "feed_loads": 256000
    },
    "calculated": { "ctr": 0.028, "cvr": 0.05, "rps": 0.04, "rpl": 0.0375 }
  },
  "data_freshness": "2026-06-14T05:00:00",
  "generated_at": "2026-06-14T05:25:11"
}

Publisher Breakdown

GET /discobeat/reporting/v1/publishers/ — per-publisher metrics for a date range, each with a daily or hourly time series.

Parameter	Type	Required	Details
from	date	–	Start date YYYY-MM-DD (UTC). Default: 6 days before to.
to	date	–	End date YYYY-MM-DD (UTC). Default: today. Max range 90 days.
granularity	string	–	Time-series bucket: day or hour. Default: day.
breakdown	string	–	Optional series split: page_type, widget_type, or widget_id.
offset	integer	–	Pagination offset. Default: 0.
limit	integer	–	Page size, 1–50. Default: 50.

With granularity=hour, each series bucket is an hour timestamp. With a breakdown, each series point also carries the breakdown field, such as a page_type of ORDER_TRACKING or THANK_YOU.

V1 400 bodies are field-keyed, e.g. {"date_range": ["Date range cannot exceed 90 days."]}.

V1 downloads: Postman collection · OpenAPI spec

Need a key or help integrating?

Your Disco representative can issue a management API key and walk through the integration. Download the V2 Postman collection to start testing right away.