API Access & Overview

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

Note: In June 2024, Chartboost introduces API version 5 for the analytics API. Support for WHAPI (v2.whapi.chartboost.com) will be sunsetting soon. Any new API endpoints will only be available for version 5 moving forwards.

Before you get started 🔗

Complete the Version 5 API access setup for the following API:

Complete the v3 API access setup for the following APIs:

Alert: The campaign and account APIs will be sunsetting soon.

Version 5 API access setup 🔗

URL: https://api.chartboost.com/v5/

Obtaining your API client credentials 🔗

The Chartboost API uses the OAuth2 standard protocol for “Client Credentials Grant” (RFC ft-ietf-oauth-v2: The OAuth 2.0 Authorization Framework) to grant authorization.

A client must pass a client_id and client_secret value to obtain an access token for authentication.

To find your client ID and client secret:

Log in to your Chartboost platform.
Click on your user icon at the top right corner.
Select Company info & settings.
Select Access Management from the left navigation column.
Click on Refresh API v5 Credentials to obtain new client ID and client secret credentials.
- For v4 users, click on Refresh API v4 Credentials to obtain your client ID and client secret credentials.
- The client secret key is only displayed when you refresh the credentials. You will not be able to see it again once you refresh or leave this page. If you loose your client secret key, you will have to re-authenticate with a new client ID and secret credentials.

Authentication 🔗

An access token is required to access and make requests to the Chartboost public API server. Obtain your access token by passing in your client id and client secret credentials to the authentication server.

Endpoint POST /oauth/token
URL https://chartboost.us.auth0.com/oauth/token

Send a request to the OAuth2 token endpoint using your client ID and client secret credentials in the request body. (Client Credentials Flow: Request tokens)

                POST /oauth/token HTTP/1.1
Host: chartboost.us.auth0.com
Content-Type: application/json

{
  "client_id": YOUR_CLIENT_ID,
  "client_secret": YOUR_CLIENT_SECRET,
  "audience": "https://public.api.gateway.chartboost.com",
  "grant_type": "client_credentials"
}

              

The Auth0 authorization server will validate and respond with an access token and expiration time in seconds; effective immediate. You must acquire a new access token after expiration, but you can use the same client credentials.

                HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"Bearer",
  "expires_in":86400
}

              

Using the public API 🔗

After authenticating against the Public API, every subsequent call must use the obtained Access Token to grant access to the protected resources. To do so, the client must use the Authorization Header with the “Bearer” token (as described in RFC ft-ietf-oauth-v2-bearer: The OAuth 2.0 Authorization Framework: Bearer Token Usage). Client call example:

Header example

                GET /v5/apps HTTP/1.1
Host: api.chartboost.com
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

              

Troubleshooting authentication errors 🔗

Any issue with the authentication will produce an error from the list below (as described in RFC 6749 - Section 5.2. Error Response):

Parameter	Response
`error`	REQUIRED. A single ASCII [USASCII] error code. Values for the “error” parameter MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E.
`error_description`	OPTIONAL. Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred. Values for the “error_description” parameter MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E.
`error_uri`	OPTIONAL. A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error. Values for the “error_uri” parameter MUST conform to the URI-reference syntax and thus MUST NOT include characters outside the set %x21 / %x23-5B / %x5D-7E.
`invalid_request`	The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.
`invalid_client`	Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate via the “Authorization” request header field, the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the “WWW-Authenticate” response header field matching the authentication scheme used by the client.
`invalid_grant`	The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.
`unauthorized_client`	The authenticated client is not authorized to use this authorization grant type.
`unsupported_grant_type`	The authorization grant type is not supported by the authorization server.
`invalid_scope`	The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.

                HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "error":"invalid_request"
}

              

v3 API access setup 🔗

Your account’s user ID and user signature are required to authenticate your API request for analytics.chartboost.com/v3/.

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.

Request and response examples 🔗

The example shows two queries: (1) an initial request to queue the job and (2) a follow-up query that uses the job ID to retrieve the results. For WHAPI and v3 endpoints, all requests should be made via HTTPS.

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

Example Request

                // 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
};

              

Example Response

                // 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 /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