API Explorer

Chartboost Mediation API Guide

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

ParameterDescriptionDefaultContingencies
dimensionsList 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
metricsList of aggregated metrics["requests", "impressions", "estimated_earnings", "ecpm", "fill_rate"]Cannot send empty list [] - minimum one metric, otherwise default metrics list will be used
filtersList 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_minEarliest date to retrieve dataToday’s date in YYYY-MM-DD formatDate range limited to 30 days (min - max)
date_maxLatest date to retrieve dataToday’s date in YYYY-MM-DD formatDate range limited to 30 days (min - max)
timezoneTime zone of the date values'America/Los_Angeles' (PST)Limited to UTC & PST

Supported Dimensions

With the Helium 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.

DimensionDescriptionType
dateDate requested (YYYY-MM-DD)string
appApp ID of the applicationstring
helium_placement_nameName of the Helium placementstring
placement_typeEither ‘interstitial’ or ‘rewarded’string
demand_sourceName of Bidding or Mediation Ad Partnerstring**
countryISO 3166-1 alpha-3 country codes***string
helium_line_item_nameName of Helium Line Item *string
partner_placement_nameName of the Mediation Demand Partner Placement *string

📘

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 Helium 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.

MetricDescriptionContingencies
requestsNumber of requests
responsesNumber of responses"Mediation" ONLY
valid_bidsNumber of valid bids"Bidding" ONLY
winning_bidsNumber of winning bids"Bidding" ONLY
impressionsNumber of impressions shown
estimated_earningsEstimated earnings in USDRounded to 2 decimal places
ecpmCalculated eCPM in USDRounded to 2 decimal places
bid_rateRatio of valid bids to bid requests"Bidding" ONLY
win_rateRatio of winning bids to valid bids"Bidding" ONLY
fill_rateRatio of impressions to ad requests
impression_show_rateRatio of impressions to winning bids"Bidding" ONLY

📘

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 Helium 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.

FilterDescriptionContingencies
appsList of application IDs the user may filter by
placementsList of Helium placements to filter by
countryList of countries to filter by
placement_typeFilter by placement typeOne or more values: ["interstitial", "rewarded"]
demand_sourceFilter by demand sourceOne or more values: ["adcolony", "admob", "applovin", "chartboost", "facebook", "tapjoy", "vungle"]
network_typeType of network to filter byString with strictly 3 options: "all", "bidding", "mediation" *

📘

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.

network_typerequestsresponsesvalid_bidswinning_bidsimpressionsestimated_earningsecpmbid_ratewin_ratewinning_bidsfill_rateimpression_show_rate
"all"
"bidding"
"mediation"

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