Mediation

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

Authentication 🔗

Access Chartboost Mediation API Explorer 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>;'

Locating your user ID and user signature 🔗

  1. Log in to your Chartboost platform
  2. Navigate to Mediation. You will be redirected to the Helium Dashboard (https://helium.chartboost.com/).
  3. From the left navigation, go to Resources > API Explorer.
  4. Your user ID and user signature is listed under Authentication

Request Body 🔗

API Route 🔗

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