API Explorer

Publisher Reporting API

This API guide 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.

📘

Note

Our Reporting API is limited to 40 requests every 10 minutes.

Authentication

Access Chartboost Mediation API Resources in order to authenticate with your User ID and User Signature.

To authenticate locally on your device rather than through the Chartboost Mediation dashboard, the following is an example of an authentication request:

curl -X "POST" "https://helium-api.chartboost.com/v1/publisher/metrics" \
  -H 'Cookie: user_id=<YOUR_USER_ID>;user_signature=<YOUR_USER_SIGNATURE>;'

Request Body

API Route

POST https://helium-api.chartboost.com/v1/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.

📘

Note

• \*\* Indicates this field should be filled in for queries in which the value for network_type in the Filters section is Mediation only.
• \*\* Indicates that the following partners are options for this field: AdColony, AdMob, Applovin, Chartboost, Facebook, Tapjoy, Vungle
• \*\*\* indicates that only 50 country codes are supported, with the exception that ‘OTHER’ must be the value if the country desired is not on the following list: ('ARE', 'ARG', 'AUT', 'AUS', 'BEL', 'BRA', 'CAN', 'CHE', 'CHL', 'CHN', 'COL', 'CZE', 'DEU', 'DNK', 'EGY', 'ESP', 'FRA', 'GBR', 'HKG', 'IDN', 'IRL', 'ISR', 'IND', 'IRN', 'ITA', 'JPN', 'KOR', 'KAZ', 'MEX', 'MYS', 'NLD', 'NOR', 'NZL', 'PER', 'PHL', 'POL', 'PRT', 'ROU', 'RUS', 'SAU', 'SWE', 'SGP', 'THA', 'TUR', 'TWN', 'UKR', 'USA', 'VNM', 'ZAF')

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.

📘

Note

\* indicates that the term Bidding and Mediation here refers to the value of the field network_type in the Filters section being set to Bidding or Mediation.

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.

📘

Note

\* indicates the list containing the combination of both of these values is the default input.

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 options for network type.

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