Dashboard Reporting API Reference
Retrieve your Blockthrough dashboard metrics from a single endpoint.
Overview
Blockthrough's Dashboard Reporting API lets you generate a metrics report to help you analyze your website's adblock recovery performance.
You'll authenticate to the API using a JSON web token.
You'll generate a report by making a
POST
request to the/Metrics
endpoint using standard HTTPS protocols.You can filter data using dimensions and metrics within the request body.
Authentication
To access the Dashboard Reporting API, you'll need to authenticate using an email and password, which will generate a JSON Web Token (JWT) that you can use for your API requests.
Follow these steps to authenticate and get a JWT:
Copy the following authentication endpoint:
Make an HTTP
POST
request to the authentication endpoint. Include your email and password in JSON. The request should look like this:
You'll receive a JWT as a response. This is your key for authenticating requests to the Dashboard Reporting API.
Once you have a JWT token, include it in the
Authorization
header of your API requests using the bearer scheme. Here's an example:
Replace your_jwt_token
with the actual JWT token obtained during the authentication process.
Keep your login credentials and JWT tokens secure.
Endpoint
The Dashboard Reporting API has one endpoint, /Metrics
:
Request body
To retrieve your dashboard's metrics, send a POST
request to the /Metrics
endpoint with a JSON request body that contains the following fields:
Field | Type | Required | Description |
---|---|---|---|
| integer | Yes | Your organization's unique identifier. |
| string | Yes | Your targeted resolution for the data (for example, "day"). |
| array of strings | Yes | The dimensions by which you want to filter the data. |
| array of strings | Yes | The specific metrics you want to retrieve. |
| object (optional) | No | An optional filter to further narrow down the data. |
| string (ISO 8601) | Yes | The start date for the data range. |
| string (ISO 8601) | Yes | The end date for the data range. |
Dimensions and available metrics
When you make a request to the /Metrics
endpoint, you can filter and customize the data you receive by using dimensions and select metrics.
Dimensions
Dimensions let you narrow down your data by specific criteria. You can include one or more dimensions to focus on specific aspects of your metrics.
Specify dimensions as an array of strings in the dimensions
field of your request body, like in the following example:
The following table lists the dimensions you can use in your request:
Dimension | Description |
---|---|
| Organization ID or name |
| Website ID or name |
| Bidder |
| Country |
| Device |
| Revenue Type |
Metrics
Metrics are the specific data points you want to retrieve from the API. You can select one or more metrics to tailor your request to your needs.
Specify metrics as an array of strings in the metrics
field of your request body, like in the following example:
The following table lists the metrics you can use in your request:
Metric | Description |
---|---|
| Acceptable Ads page views. |
| Percent of Adblock page views opted in to Acceptable Ads. |
| Adblock Plus page views. |
| Percent of page views that are Adblock Plus. |
| The total number of auctions performed to fill available AdBlock (Acceptable Ads) impressions. |
| Number of bids for the date range selected. |
| Number of clicks for the date range selected. |
| Gross revenue per 1000 impressions served. |
| Backfill creatives rendered only when there is no programmatic auction winner. |
| Programmatic impressions divided by total auctions. |
| Google Ad Manager empty responses. |
| Google Ad Manager errors. |
| Google Ad Manager exceptions. |
| Total gross revenue generated from monetizing AdBlock users. |
| Total number of monetized impressions. |
| Non-Adblock Plus page views. |
| Total page views. |
| Total number of requests sent to SSPs. |
| Revenue per 1000 Acceptable Ads page views. |
| Total number of timeouts. |
| An ad that's at least 50% visible for more than one second. |
You can combine dimensions and metrics to tailor your API requests to access precise data that fits your analytics needs.
The following example shows a request body that includes both dimensions and metrics:
Sample request and response
This sample request includes the website_id
dimension as well as the gross_revenue
and requests
metrics:
Last updated