API Access & Overview

With the Chartboost API, you can access campaign and app analytics, retrieve account and earnings information and more. To get started, review the following authentication setup, HTTP Methods, and API rules before delving into specific APIs.

Authentication 🔗

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

Locating your user ID and user signature 🔗

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

Note: Chartboost is hard at work redesigning, migrating, and improving dashboards & platform services. Please bear with us as some tools, features, and information may be in odd areas.

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.

Old Job Endpoint 🔗

Status: To be deprecated soon

https://analytics.chartboost.com/v3/metrics/jobs/[jobId]

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
  file.write(jobId);
  }
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 } };

              

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.
You can then use the ID to check the job’s status in a subsequent request, using this new endpoint: GET /v3/metrics/jobs/[jobId]?status=true.
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/[jobId].
If you try to retrieve your data before the job is finished, you may receive an empty or incomplete response.

New Job Endpoint 🔗

Status: Live

https://v2.whapi.chartboost.com/metrics/jobs/[jobId]

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://v2.whapi.chartboost.com/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
  file.write(jobId);
  }
else {
  // handle failure
};

              

                // pseudo-code example of retrieving the result by jobId
query_url = "https://v2.whapi.chartboost.com/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 } };

              

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.
You can then use the ID to check the job’s status in a subsequent request, using this new endpoint: GET /metrics/jobs/{jobId}?status=true.
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 /metrics/jobs/{jobId}.
If you try to retrieve your data before the job is finished, you will either receive a 404 response if the job was not initialized yet, or a 200 response with an appropriate message that the job is not finished yet.

Query results are stored and available for 60 minutes before deletion. The default content-type is text/tab-separated-values;charset=UTF-16LE where results are returned in TSV form, but text/csv;charset=utf-8 is also available and it is returned when the request has the parameter csv_format set to CSV.

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.

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.

Advertising