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:

1. Copy the following authentication endpoint:

https://dash.api.blockthrough.com/twirp/dashboard.ApiV1/SignIn

1. Make an HTTP POST request to the authentication endpoint. Include your email and password in JSON. The request should look like this:

curl --request POST \
     --url https://dash.api.blockthrough.com/twirp/dashboard.ApiV1/SignIn \
     --header 'Content-Type: application/json' \
     --data '{
       "email": "your_email_address",
       "password": "your_password"
     }'

1. You'll receive a JWT as a response. This is your key for authenticating requests to the Dashboard Reporting API.

2. Once you have a JWT token, include it in the Authorization header of your API requests using the bearer scheme. Here's an example:

curl --request POST \
     --url https://dash.api.blockthrough.com/twirp/dashboard.ApiV1/Metrics \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'Authorization: Bearer <your_jwt_token>' \
     --data '{"dimensions": ["org_id"], "end_date": "2023-01-05T00:00:00Z", "id": 1,"metrics": ["impressions"],"resolution": "day","start_date": "2023-01-01T00:00:00Z"}'

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:

https://dash.api.blockthrough.com/twirp/dashboard.ApiV1/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
id	integer	Yes	Your organization's unique identifier.
resolution	string	Yes	Your targeted resolution for the data (for example, "day").
dimensions	array of strings	Yes	The dimensions by which you want to filter the data.
metrics	array of strings	Yes	The specific metrics you want to retrieve.
filter	object (optional)	No	An optional filter to further narrow down the data.
start_date	string (ISO 8601)	Yes	The start date for the data range.
end_date	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:

"dimensions": ["org_id", "website_id"]

The following table lists the dimensions you can use in your request:

Dimension	Description
org_id or org_name	Organization ID or name
website_id or website_name	Website ID or name
bidder	Bidder
country	Country
device	Device
revenue_type	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:

"metrics": ["impressions", "requests"]

The following table lists the metrics you can use in your request:

Metric	Description
aa_page_views	Acceptable Ads page views.
aa_page_views_rate	Percent of Adblock page views opted in to Acceptable Ads.
ab_page_views	Adblock Plus page views.
ab_page_views_rate	Percent of page views that are Adblock Plus.
auctions	The total number of auctions performed to fill available AdBlock (Acceptable Ads) impressions.
bids	Number of bids for the date range selected.
clicks	Number of clicks for the date range selected.
cpm	Gross revenue per 1000 impressions served.
default_creatives	Backfill creatives rendered only when there is no programmatic auction winner.
fill_rate	Programmatic impressions divided by total auctions.
gam_empty_responses	Google Ad Manager empty responses.
gam_errors	Google Ad Manager errors.
gam_exceptions	Google Ad Manager exceptions.
gross_revenue	Total gross revenue generated from monetizing AdBlock users.
impressions	Total number of monetized impressions.
non_ab_page_views	Non-Adblock Plus page views.
page_views	Total page views.
requests	Total number of requests sent to SSPs.
rpm	Revenue per 1000 Acceptable Ads page views.
timeouts	Total number of timeouts.
viewable_impressions	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:

{
  "id": 1,
  "resolution": "day",
  "dimensions": ["org_id", "website_id"],
  "metrics": ["impressions", "requests"],
  "start_date": "2023-01-01T00:00:00Z",
  "end_date": "2023-01-05T00:00:00Z"
}

Sample request and response

This sample request includes the website_id dimension as well as the gross_revenue and requests metrics:

Request

curl --request POST \
     --url https://dash.api.blockthrough.com/twirp/dashboard.ApiV1/Metrics \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'Authorization: Bearer <your_jwt_token>' \
     --data '
{
  "id": 2,
  "resolution": "day",
  "dimensions": [
    "ts",
    "website_id"
  ],
  "metrics": [
    "gross_revenue",
    "requests"
  ],
   "start_date": "2023-01-01T00:00:00Z",
  "end_date": "2023-01-05T00:00:00Z"
}
'

Response 200 OK

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 2,
  "data": [
    {
      "gross_revenue": 1154.779997,
      "ts": "2023-10-01",
      "website_name": "example.com"
    },
    {
      "gross_revenue": 0.77,
      "ts": "2023-10-01",
      "website_name": "unknown"
    }
  ]
}