API Overview

With the Chartboost API, you can access campaign and app analytics, retrieve account and earnings information and more.

Authentication 🔗

Your account’s user ID and user signature are required to authenticate your API request.

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

HTTP Methods 🔗

The required HTTP methods GET,, POST, PUT, etc., vary by the endpoint. All requests should be made via HTTPS. The example for analytics listed below shows two queries an initial request to queue the job and a follow-up query that uses the job ID to retrieve the results.

// pseudo-code example for initial query request
query_url = "https://analytics.chartboost.com/v3/metrics/campaign?" + query_params
query_params = "... groupBy=app,creative ..."

response = get(query_url);
if (response.status = 202) {
  jobId = response.parse('jobId');
  // capture the jobId for retrieve() function
else {
  // handle failure

// pseudo-code example of retrieving the result by jobId
query_url = "https://analytics.chartboost.com/v3/metrics/jobs/" + jobId
query_params = ""
created = get(query_url + “?status=true”); if (created.status == 201) { response = get(query_url); if (response.status == 200) { // get nerdy with data } else { // handle failure } };
  1. After receiving GET /campaign and GET /install queries that use the groupBy parameter, the Chartboost API will respond with a job ID that serves as a confirmation that the request has been accepted and queued for processing.
  2. You can then use the ID to check the job’s status in a subsequent request, using this new endpoint: GET /v3/metrics/jobs/[job_id]?status=true.
  3. The query will return 201 {status: "created"} if the job results are ready to be collected. Once your system receives that response, you can pull the data like so: ` GET /v3/metrics/jobs/[job_id]`.
  4. If you try to retrieve your data before the job is finished, you may receive an empty or incomplete response.

Query results are stored and available for up to 24 hours before deletion. The only supported content-type is text/comma-separated-values;charset=UTF-8 where results are returned in CSV form.

API Methods 🔗

The Chartboost API features four different types of methods: analytics methods, app methods, campaign methods, and account methods. Each method type has unique endpoints.

  • Add parameters to build your requests for testing. Required parameters are noted in the documentation.
  • Most analytics reports returned from our API are in JSON format. Specific queries are returned in CSV (comma-separated value) format. Learn more about formatting
  • Please follow the Chartboost API rules listed below.

Chartboost API Rules 🔗

These guidelines help us ensure that all customers’ requests are returned quickly. If you do not respect these limits, your API access will be limited.

  • Space out your requests. If you need to receive five different reports each day, don’t send all five requests at the same time. Give your requests at least a few minutes of breathing room. Your API access will be limited if you make more than 1 query per minute.
  • Group your apps into a single request. Instead of sending a unique API request for each app, drop the appId parameter and let the API return data for all the apps.

Last modified November 27, 2023