Reporting API

Pull delivery and spend metrics for your account. A single read-only endpoint returns daily rows of requests, impressions and spend, sliced by the dimensions you ask for.

Version · v1 Transport · HTTPS GET + JSON Currency · USD

Overview

The Reporting API is a read-only HTTP endpoint. You issue a GET with a date range and an optional set of dimensions; Reticle returns aggregated daily rows of request opportunities, impressions and spend. There are two variants — one for supply partners and one for demand partners — that share an identical request and response shape.

All dates are UTC and ranges are inclusive on both ends.
The finest granularity is one day; there is no hourly reporting.
Monetary values are in USD, as raw values to four decimal places.
Results are paged.

Authentication

Every request carries an api_key, passed as a query parameter. The key and your base endpoint are issued per partner — contact us to obtain them. Keep the key server-side; it grants access to your account's figures.

Endpoints

Two endpoints, chosen by which side of the exchange you sit on. Both take the same parameters and return the same shape.

Method	Path	For
GET	/openapi/v1/reporting/supply	Supply partners (SSP).
GET	/openapi/v1/reporting/demand	Demand partners (DSP).

The host is your issued base endpoint; the paths above are appended to it.

Example request · cURL

curl "https://YOUR-ENDPOINT/openapi/v1/reporting/supply\
?api_key=YOUR_API_KEY\
&start_date=2026-07-01\
&end_date=2026-07-19\
&dimensions=date,country,format\
&page=1\
&page_size=1000"

Query parameters

Parameter	Required	Description
api_key	yes	Partner key. See Authentication.
start_date	yes	Start of the range, `YYYY-MM-DD`, UTC. Inclusive.
end_date	yes	End of the range, `YYYY-MM-DD`, UTC. Inclusive.
dimensions	no	Comma-separated subset of `date`, `region`, `country`, `format`. Omit to aggregate the whole range into a single row.
page	no	Page number. Default `1`.
page_size	no	Rows per page. Default `1000`, maximum `10000`.

Constraints

A request that violates any of these returns HTTP 400:

The range end_date − start_date must be 31 days or fewer.
end_date must be T-1 or earlier — today's and future dates are not queryable.
Granularity is fixed at one day; there is no finer slice.
page_size must not exceed 10000.

Response

Every response is a JSON envelope with a status code, a message, and a data object holding pagination metadata and the result rows.

Response · JSON

{
  "code": 0,
  "message": "ok",
  "data": {
    "currency": "USD",
    "page": 1,
    "page_size": 1000,
    "total": 1342,
    "rows": [
      {
        "date": "2026-07-19",
        "region": "ap",
        "country": "US",
        "format": "banner",
        "request_oppo": 1284322,
        "impressions": 41100,
        "spend": 82.4413
      }
    ]
  }
}

Envelope

Field	Type	Description
code	integer	`0` on success; a non-zero value indicates an error. See Errors.
message	string	Human-readable status. `ok` on success.
data	object	Result payload.

data object

Field	Type	Description
currency	string	Currency of monetary fields. Always `USD`.
page	integer	Current page number.
page_size	integer	Rows per page.
total	integer	Total number of rows across all pages for this query.
rows	object[]	Array of result rows. See Dimensions & metrics.

Dimensions & metrics

Each row carries the metrics below, plus one column per requested dimension. Dimension columns appear only when requested in dimensions; with no dimensions, a single aggregated row is returned for the whole range.

Dimensions

Field	Type	Description
date	string	Day, `YYYY-MM-DD` (UTC). Present only if `date` is requested.
region	string	Reticle serving region: `ap`, `us` or `eu`. Present only if `region` is requested.
country	string	End-user country, ISO 3166-1 alpha-2 (e.g. `US`). Present only if `country` is requested.
format	string	Creative format (e.g. `banner`). Present only if `format` is requested.

Metrics

Field	Type	Description
request_oppo	integer	Request opportunities — ad/bid requests eligible for this slice.
impressions	integer	Served impressions.
spend	float	Spend in `currency` (USD), a raw value to four decimal places.

Errors

Successful requests return HTTP 200 with code: 0 and message: "ok". Any non-zero code indicates an error, with message describing it. Requests that violate the constraints return HTTP 400.

For the full list of error codes, contact us.

Changelog

Version		Change
v1		Initial release: supply and demand reporting endpoints, date / region / country / format dimensions, request / impression / spend metrics.