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

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.

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.

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.

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.

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"
  }
}