Reporting API

The Reporting API returns the same data you see on the Dashboard’s Analytics page.

Use it when you want to pull Pinokio data into your own systems, dashboards, or pipelines.

Parameter names match the short codes used in Pre-bid and Post-bid.

Authentication

The Reporting API uses HTTP Basic Auth.

Username — your Pinokio Customer ID.
Password — your Reporting API key.

Both values live in the Integrations → Reporting section of the Dashboard. If you cannot find them, ask your Pinokio account manager.

Endpoint

GET <pinokio-reporting-url>

Your Pinokio account manager will provide the base URL during onboarding. All parameters are passed via the query string.

Date range

Every request must specify the time window the report covers.

Parameter	Required	Description
`start_date`	Yes	Start of the window, `YYYY-MM-DD`.
`end_date`	Yes	End of the window, `YYYY-MM-DD`. Inclusive.

Group by

Use group_by to choose which dimensions the data is rolled up by. Pass a comma-separated list of dimension names. The same dimensions appear in the Dashboard’s Analytics column picker.

&group_by=date,pub,sid

Available dimensions:

Dimension	Description
`date`	Day of the transaction.
`hour`	Hour of the transaction. Use with `date` for hourly breakdowns.
`pub`	Publisher ID.
`sid`	Supplier ID.
`app`	App ID / bundle ID.
`dmn`	Domain.
`node`	Server or prebid instance.
`adt`	Ad type — `1` Banner, `2` Video, `3` Audio, `4` Native.
`geo`	Two-letter ISO country code.
`dvt`	Device type.
`os`	Operating system.
`browser`	Browser family.
`env`	Environment — `site`, `app`, or `dooh`.
`cmp`	Campaign ID.
`adv`	Advertiser ID.
`p1`–`p5`	Custom reporting dimensions you passed through Post-bid.

Filters

Every filter is optional. Pass them as query parameters; multiple values for the same filter are comma-separated.

Filter	Description
`pub`	One or more publisher IDs.
`sid`	One or more supplier IDs.
`app`	One or more app IDs / bundle IDs.
`dmn`	One or more domains.
`geo`	Two-letter ISO country codes.
`dvt`	Device type values.
`os`	Operating systems.
`browser`	Browser families.
`env`	`site`, `app`, `dooh`.
`adt`	`1` Banner, `2` Video, `3` Audio, `4` Native.
`cmp`	Campaign IDs.
`adv`	Advertiser IDs.
`node`	Server or prebid instance IDs.
`p1`–`p5`	Match on custom dimensions.

Pagination

Long result sets are paginated.

Parameter	Required	Description
`limit`	No	Maximum number of rows to return. Default `20`, max `1000`.
`offset`	No	Starting index in the result set. Default `0`.

Example request

curl -u "<customer_id>:<api_key>" \
  "<pinokio-reporting-url>?start_date=2026-05-24&end_date=2026-05-24&group_by=sid,geo&geo=US,GB&limit=100"

Response

200 OK — body is a JSON object with meta describing the query and rows containing the aggregated data.

{
  "meta": {
    "start_date": "2026-05-24",
    "end_date": "2026-05-24",
    "group_by": ["sid", "geo"],
    "total_rows": 142,
    "returned_rows": 100,
    "offset": 0
  },
  "rows": [
    {
      "sid": "supplyhub.com",
      "geo": "JP",
      "total_transactions": 12450,
      "valid_transactions": 11200,
      "invalid_transactions": 1250,
      "sivt_transactions": 980,
      "givt_transactions": 270
    }
  ]
}

Row fields

Each row contains:

one value for each dimension named in group_by,
the aggregated transaction metrics for that group:

Metric	Description
`total_transactions`	Total recorded transactions in the group.
`valid_transactions`	Classified as valid.
`invalid_transactions`	Flagged as IVT — the sum of SIVT and GIVT.
`sivt_transactions`	Flagged as Sophisticated IVT.
`givt_transactions`	Flagged as General IVT.

Common errors

Code	Meaning
`400`	Bad request — missing required parameter, unknown dimension or filter, malformed date.
`401`	Customer ID or Reporting API key is wrong, or the Basic Auth header is missing.
`422`	Validation error — invalid parameter values.
`429`	Too many requests — wait and retry.