Reporting API V2 · Channel

Channel Reporting API

Reference for Channel-scoped report requests and JSON responses.

Quickstart API reference

API scope

Choose the scope assigned to your secret key.

// Channel · quickstart

First request

Store the Channel management secret key in server-side secrets storage.
Send GET /discobeat/reporting/v2/report/ with the X-API-Key header.
Add from and to together for inclusive UTC dates, or omit both to use the defaults.

curl

curl -H "X-API-Key: disco_sk_live_..." \
  "https://api.disconetwork.com/discobeat/reporting/v2/report/"

Defaults

Selection	Default
Dates	Latest 7 UTC dates in the reporting window
Metrics	Authenticated Channel metric set
Time grain	total
Sort order	desc
Pagination	offset 0 and limit 50

Downloads

Postman collection

Report request with an api_key variable.

OpenAPI specification

OpenAPI 3.0.3 report schema.

// Channel · request

Authentication and endpoint

Field	Value
Base URL	https://api.disconetwork.com
Method and path	GET /discobeat/reporting/v2/report/
Authentication	X-API-Key header with a Channel management secret key
Scope	Channel assigned to the secret key
Secret-key prefix	disco_sk_live_…

Send requests from server-side code. The key fixes the Channel scope and no Channel ID parameter is accepted.

// Channel · parameters

Query parameters

Parameter	Type	Req	Details
from	date	–	First UTC date in YYYY-MM-DD format, inclusive. Required when to is supplied.
to	date	–	Last UTC date in YYYY-MM-DD format, inclusive. Required when from is supplied and cannot be future.
metrics	comma-separated list	–	Metric columns in response order. Defaults to the authenticated Channel metric set.
time_grain	string	–	total, day, week, month, or hour. Default is total.
group_by	comma-separated list	–	Up to three unique values from publisher, page_type, widget_type, and widget_id.
sort_order	string	–	desc returns latest periods first and asc returns oldest periods first. Default is desc.
sort_by	string	–	period_start, a selected metric, or a selected grouping field. Default is period_start.
sort_direction	string	–	asc or desc. Defaults to sort_order.
publisher_ids	comma-separated list	–	Include matching Publisher UUIDs. Maximum 250 values.
page_types	comma-separated list	–	Include matching page types. MODAL is excluded. Maximum 250 values.
widget_types	comma-separated list	–	Include matching widget types. Maximum 250 values.
offset	integer	–	Rows to skip after sorting. Default is 0.
limit	integer	–	Page size from 1 to 250. Default is 50.

// Channel · UTC periods

Dates and periods

Rule	Contract
Date pair	from and to are optional together. Supplying only one returns 400
No dates	Non-hourly requests use the latest 7 UTC dates in the reporting window
No hourly dates	Uses up to 3 UTC dates in the hourly reporting window
Query boundaries	from and to are inclusive UTC calendar dates
Response boundaries	period_start is inclusive. period_end is exclusive
Weeks	UTC weeks begin Monday. Edge periods are clipped to the query
Months	UTC calendar months. Edge periods are clipped to the query

Time grains

Value	Rows and range
total	One period for all matching activity
day	Matching activity grouped by UTC date
week	Matching activity grouped by Monday-based UTC week
month	Matching activity grouped by UTC calendar month
hour	Matching activity grouped by UTC hour. Maximum 3 inclusive dates

// Channel · metrics

Metrics and formulas

Calculated metrics use aggregated measured totals. Ratios are returned as decimal values rather than percentages.

Measured metrics

Metric	Definition
impressions	Brand ad impressions
clicks	Brand ad clicks
conversions	Disco-attributed conversions
channel_payout	Channel payout amount
revenue_with_email	Net billable revenue from activity with email
revenue_without_email	Net billable revenue from activity without email
feed_loads	Widget or feed load events
widget_displays	Widget display events
viewable_widget_displays	Widget displays counted as viewable
order_revenue_amount	Attributed order revenue amount
attributed_ad_spend_amount	Attributed ad spend amount
billable_ad_spend_amount	Billable ad spend amount

Calculated metrics

Metric	Formula	Definition
ctr	clicks / impressions	Click-through rate
cvr	conversions / clicks	Channel conversion rate
rpl	channel_payout / feed_loads	Payout per feed load
attributed_cpa	attributed_ad_spend_amount / conversions	Attributed cost per acquisition

Value rule	Contract
Zero denominator	Calculated metric is 0
Ratio precision	Rounded to 4 decimal places
Monetary precision	Rounded to 2 decimal places

A documented metric may not be enabled for every Channel. Contact Disco if METRIC_NOT_AVAILABLE is returned.

// Channel · dimensions

Groupings and filters

Parameter	Values	Effect
group_by	publisher, page_type, widget_type, widget_id	Accepts up to 3 grouping keys. publisher adds publisher_id and publisher_name
publisher_ids	Publisher UUIDs	Filters rows without adding a column
page_types	Page-type values	Filters rows without adding a column
widget_types	Widget-type values	Filters rows without adding a column

Multiple groupings return one row for each observed combination.
A filtered dimension appears in data only when it is also included in group_by.
All time grains support up to 3 unique groupings.

// Channel · report

Report request

GET/discobeat/reporting/v2/report/

curl

curl -G -H "X-API-Key: disco_sk_live_..." \
  --data-urlencode "from=2026-07-18" \
  --data-urlencode "to=2026-07-20" \
  --data-urlencode "time_grain=day" \
  --data-urlencode "group_by=publisher,page_type" \
  --data-urlencode "metrics=impressions,clicks,conversions,channel_payout,ctr,cvr" \
  --data-urlencode "page_types=ORDER_TRACKING,THANK_YOU" \
  --data-urlencode "sort_order=asc" \
  --data-urlencode "offset=0" \
  --data-urlencode "limit=50" \
  "https://api.disconetwork.com/discobeat/reporting/v2/report/"

Sorting and pagination

Rule	Contract
Sort	Rows are sorted before pagination
Page	data contains up to limit rows starting at offset
Total	pagination.total is the full row count
Continue	Add data.length to offset while pagination.has_more is true
Summary	summary covers all matching rows before pagination

JSON response

Field	Value
data	Paginated flat rows with period, grouping, and selected metric fields
summary	Selected metrics across all matching rows
pagination	offset, limit, total, and has_more
meta	timezone, data_through, and request_id

200 application/json

{
  "data": [
    {
      "period_start": "2026-07-18T00:00:00Z",
      "period_end": "2026-07-19T00:00:00Z",
      "publisher_id": "9aa17f8c-7746-4218-9025-83d38c406179",
      "publisher_name": "Example Publisher",
      "page_type": "ORDER_TRACKING",
      "impressions": 4584,
      "clicks": 180,
      "conversions": 46,
      "channel_payout": 189.90,
      "ctr": 0.0393,
      "cvr": 0.2556
    }
  ],
  "summary": {
    "impressions": 225072,
    "clicks": 8928,
    "conversions": 2234,
    "channel_payout": 6546.24,
    "ctr": 0.0397,
    "cvr": 0.2502
  },
  "pagination": {
    "offset": 0,
    "limit": 50,
    "total": 36,
    "has_more": false
  },
  "meta": {
    "timezone": "UTC",
    "data_through": "2026-07-20T00:00:00Z",
    "request_id": "7e9fe348-7558-4e28-b8c6-b26ea44899eb"
  }
}

// Channel · limits

Limits and availability

Rule	Limit
Non-hourly range	Must fit available reporting history
Hourly range	3 inclusive UTC dates within available hourly history
Groupings	3 for every time grain
Filter values	250 per filter
Page size	50 by default and 250 maximum
Result rows	10,000 before pagination
Available history	Request dates must fall within the available window
data_through	Latest available data period, shown by its UTC start time. Not a refresh time
No matching activity	200 with empty data and zero-valued summary metrics

// Channel · errors

Errors

Status or code	Condition
400 validation	Malformed or unknown parameters, unpaired dates, empty lists, and duplicate or unsupported metrics or groupings
METRIC_NOT_AVAILABLE	Response lists requested fields in unsupported_metrics and permitted fields in allowed_metrics
REPORTING_DATA_UNAVAILABLE	No reporting data is available for the Channel
DATE_RANGE_OUTSIDE_AVAILABLE_WINDOW	Dates are outside available history. Response may include available_window
REPORT_ROW_LIMIT_EXCEEDED	Result exceeds 10,000 rows before pagination
REPORTING_SOURCE_ROW_LIMIT_EXCEEDED	Historical request is too large to process
401	Missing, invalid, public, revoked, or expired secret key
405	Method is not GET

400 application/json

{
  "code": "METRIC_NOT_AVAILABLE",
  "unsupported_metrics": ["channel_payout"],
  "allowed_metrics": ["impressions", "clicks", "ctr"]
}

Channel · API access

Secret-key access

Ask your Disco contact for a Channel management secret key.

Contact Disco