Mediation Reporting API

The Mediation Reporting API provides information on how app publishers leveraging Chartboost Mediation can send and receive requests to gather reporting data such as revenue, impressions, and other metrics.

Obtaining your API client credentials 🔗

The Chartboost API uses the OAuth2 standard protocol for “Client Credentials Grant” (RFC ft-ietf-oauth-v2: The OAuth 2.0 Authorization Framework) to grant authorization.

A client must pass a client_id and client_secret value to obtain an access token for authentication.

To find your client ID and client secret:

  1. Log in to your Chartboost platform.
  2. Click on your user icon at the top right corner.
  3. Select Company info & settings.
  4. Select Access Management from the left navigation column.
  5. Click on Refresh API v5 Credentials to obtain new client ID and client secret credentials.
    • The client secret key is only displayed when you refresh the credentials. You will not be able to see it again once you refresh or leave this page. If you loose your client secret key, you will have to re-authenticate with a new client ID and secret credentials.

Authentication 🔗

An access token is required to access and make requests to the Chartboost public API server. Obtain your access token by passing in your client id and client secret credentials to the authentication server.

Endpoint POST /oauth/token
URL https://chartboost.us.auth0.com/oauth/token

Send a request to the OAuth2 token endpoint using your client ID and client secret credentials in the request body. (Client Credentials Flow: Request tokens)

POST https://chartboost.us.auth0.com/oauth/token HTTP/1.1
Host: chartboost.us.auth0.com
Content-Type: application/json

{
  "client_id": YOUR_CLIENT_ID,
  "client_secret": YOUR_CLIENT_SECRET,
  "audience": "https://public.api.gateway.chartboost.com",
  "grant_type": "client_credentials"
}

The Auth0 authorization server will validate and respond with an access token and expiration time in seconds; effective immediate. You must acquire a new access token after expiration, but you can use the same client credentials.

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"Bearer",
  "expires_in":86400
}

Using the public API 🔗

After authenticating against the Public API, every subsequent call must use the obtained Access Token to grant access to the protected resources. To do so, the client must use the Authorization Header with the “Bearer” token (as described in RFC ft-ietf-oauth-v2-bearer: The OAuth 2.0 Authorization Framework: Bearer Token Usage). Client call example:

Header example

POST https://helium-api.chartboost.com/v2/publisher/metrics HTTP/1.1
Host: helium-api.chartboost.com
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

Request Body 🔗

API Route 🔗

POST https://helium-api.chartboost.com/v2/publisher/metrics

Parameter Description Default Contingencies
dimensions List of fields used to break down data [“date”, “app”, “helium_placement_name”, “placement_type”, “demand_source”,”country”] Cannot send empty list [] - minimum one dimension, otherwise default dimensions list will be used
metrics List of aggregated metrics [“requests”, “impressions”, “estimated_earnings”, “ecpm”, “fill_rate”] Cannot send empty list [] - minimum one metric, otherwise default metrics list will be used
filters List of attributes to filter data by [‘apps’, ‘placements’, ‘country’, ‘placement_type’, ‘demand_source’, ‘network_type’] Cannot send empty list filters - minimum filter list length is 1
date_min Earliest date to retrieve data Today’s date in YYYY-MM-DD format Date range limited to 30 days (min - max)
date_max Latest date to retrieve data Today’s date in YYYY-MM-DD format Date range limited to 30 days (min - max)
timezone Time zone of the date values ‘America/Los_Angeles’ (PST) Limited to UTC & PST

Supported Dimensions 🔗

With the Mediation reporting API, you are not required to input any dimensions to the request body - this will result in the default values being used. However, if you elect to input dimension values, the list cannot be empty as you must provide at least one of the following accepted values to result in a successful query.

Dimension Description Type
date Date requested (YYYY-MM-DD) string
app App ID of the application string
helium_placement_name Name of the Mediation placement string
placement_type Either ‘interstitial’ or ‘rewarded’ string
demand_source Name of Bidding or Mediation Ad Partner string**
country ISO 3166-1 alpha-3 country codes*** string
helium_line_item_name Name of Mediation Line Item * string
partner_placement_name Name of the Mediation Demand Partner Placement * string

Supported Metrics 🔗

With the Mediation reporting API, you are not required to input any metrics to the request body - this will result in the default values being used. However, if you elect to input metric values, the list cannot be empty. At least one of the following accepted values must be provided to result in a successful query.

Metric Description Contingencies
requests Number of requests  
responses Number of responses “Mediation” ONLY
valid_bids Number of valid bids “Bidding” ONLY
winning_bids Number of winning bids “Bidding” ONLY
impressions Number of impressions shown  
estimated_earnings Estimated earnings in USD Rounded to 2 decimal places
ecpm Calculated eCPM in USD Rounded to 2 decimal places
bid_rate Ratio of valid bids to bid requests “Bidding” ONLY
win_rate Ratio of winning bids to valid bids “Bidding” ONLY
fill_rate Ratio of impressions to ad requests  
impression_show_rate Ratio of impressions to winning bids “Bidding” ONLY

Supported Filters 🔗

With the Mediation reporting API, you are not required to input any filters to the request body. However, if you elect to set filters, the list cannot be empty. At least one of the following accepted values must be provided to result in a successful query.

Filter Description Contingencies
apps List of application IDs the user may filter by  
placements List of Mediation placements to filter by  
country List of countries to filter by  
placement_type Filter by placement type One or more values: [“interstitial”, “rewarded”, “banner”, “rewarded_interstitial”, “adaptive_banner”]
demand_source Filter by demand source One or more values: [“admob”, “applovin”, “chartboost”, “facebook”, “fyber”, “google_googlebidding”, “hyprmx”, “inmobi”, “ironsource”, “mintegral”, “mobilefuse”, “unity”, “vungle”]
network_type Type of network to filter by String with strictly 3 options: “all”*, “bidding”, “mediation”*

Parameter Compatibility 🔗

Some combinations of parameters are incompatible with each other. The following table shows which fields can be used in conjunction with the three network_type options.

Field all bidding mediation
requests
responses
valid_bids
winning_bids
impressions
estimated_earnings
ecpm
bid_rate
win_rate
winning_bids
fill_rate
impression_show_rate

Example JSON Request 🔗

The following is an example of a very basic request with only three inputted fields - leaving the rest to be the default settings.

{
  "date_min": "2020-06-23",
  "date_max": "2020-06-25",
  "timezone": "UTC"
}

Example JSON Response 🔗

The following is an example response of a successfully inputted query.

  "data": [
    {
      "app": "53721724c26ee432aa854f55",
      "date": "2020-06-24",
      "ecpm": 11.27,
      "estimated_earnings": 26.16,
      "fill_rate": 0.03,
      "impressions": 2321,
      "placement_type": "interstitial",
      "requests": 79415,
      "responses": 25192
    },
    {
      "app": "53721724c26ee432aa854f55",
      "date": "2020-06-24",
      "ecpm": 9.92,
      "estimated_earnings": 4.17,
      "fill_rate": 0.01,
      "impressions": 420,
      "placement_type": "rewarded",
      "requests": 44260,
      "responses": 13152
    },
    {
      "app": "537220541873da7ee366aee7",
      "date": "2020-06-24",
      "ecpm": 10.78,
      "estimated_earnings": 8.87,
      "fill_rate": 0.05,
      "impressions": 823,
      "placement_type": "interstitial",
      "requests": 17920,
      "responses": 6433
    },
    {
      "app": "537220541873da7ee366aee7",
      "date": "2020-06-24",
      "ecpm": 7.48,
      "estimated_earnings": 1.71,
      "fill_rate": 0.02,
      "impressions": 229,
      "placement_type": "rewarded",
      "requests": 14243,
      "responses": 4815
    }
  ],
  "process_time": 0.008205890655517578,
  "query_time": 0.23745250701904297,
  "row_count": 4
}

Errors 🔗

Invalid requests will result in a 400 status code with the relevant response body.

The following is an example error response.

{
  "code": 400,
  "name": "Bad Request",
  "description": "ValidationError",
  "errors": {
    "win_rate": "'win_rate' metric is for network_type 'bidding' only"
  }
}