Analytics API

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.

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

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/[jobId]?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/[jobId].
4. 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 } };

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 /metrics/jobs/{jobId}?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 /metrics/jobs/{jobId}.
4. 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.

Migrating to Analytics API: WHAPI v2 🔗

WHAPI v2 is backward compatible, hence the interface of the old API is matched by the new API. The requests will not need any changes in parameters, and the responses will match the expected schema.

For migrations 2 things need to be changed:

1. Update URL from https://analytics.chartboost.com to https://v2.whapi.chartboost.com.
2. Remove /v3 from the endpoint paths. For example:
   • /v3/metrics/campaign changes to /metrics/campaign
   • /v3/metrics/jobs/{jobId} changes to /metrics/jobs/{jobId}
   • /v3/reports/{report_id} changes to /reports/{report_id}

What is new in WHAPI v2? 🔗

New Whapi include New Monetization endpoint (link) providing comparisons between different time periods to gather valuable performance insights.

Endpoints 🔗

Campaign Analytics 🔗

The campaign analytics endpoint provides detailed reports that can be grouped by app, campaign, campaign type, campaign target, date, target creative, creative or country. Be advised that when setting the groupBy field to app, creative, or country, a job ID will be returned by the Queued Analytics System. The result can then be retrieved by sending the job ID to the /jobs endpoint documented below.

For the new WHAPI endpoint,

• data is available from January 1, 2018 when groupBy=app, country, creative
• data is available from January 1, 2018 when timezone=pst and groupBy=campaign (default), campaign_target, campaign_type, date
• data is available from March 1, 2020 when timezone=utc and groupBy=campaign (default), campaign_target, campaign_type, date
• data is available from June 16, 2020 when groupBy=target_creative

Example Request 🔗

• New Endpoint
• Old Endpoint

• https://v2.whapi.chartboost.com/metrics/campaign?dateMin={Minimum date}&dateMax={Maximum date}&userId={Chartboost customer’s user ID}&userSignature={CB customer’s user signature}
  

• https://analytics.chartboost.com/v3/metrics/campaign?dateMin={Minimum date}&dateMax={Maximum date}&userId={Chartboost customer’s user ID}&userSignature={CB customer’s user signature}
  

Parameter 🔗

Response Fields 🔗

Analytics 🔗

For groupBy = campaign, campaign_target, campaign_type, date, and target_creative, the API response will return a JSON with the following schema:

Queued Analytics 🔗

For groupBy = app, app,creative, country, creative, the API response is a job ID which can be used with /metrics/jobs to retrieve CSV files of the following schema:

App Analytics 🔗

The app analytics endpoint provides detailed reports that can be grouped by app, ad type, ad location, campaign type, county date, or platform.

For the new WHAPI endpoint,

• data is available from January 1, 2018 when groupBy=ad_location, ad_type, app (default), campaign, date, platform
• data is available from June 16, 2020 when groupBy=country

Example Request 🔗

• New Endpoint
• Old Endpoint

• https://v2.whapi.chartboost.com/metrics/app?dateMin={Minimum date}&dateMax={Maximum date}&userId={Chartboost customer’s user ID}&userSignature={CB customer’s user signature}
  

• https://analytics.chartboost.com/v3/metrics/app?dateMin={Minimum date}&dateMax={Maximum date}&userId={Chartboost customer’s user ID}&userSignature={CB customer’s user signature}
  

Parameters 🔗

Response Fields 🔗

The API response will return a JSON with the following schema:

Export Installs 🔗

The export installs endpoint provides a full list of all installs received and/or provided. Please note that this endpoint will always return a Job ID from the Queued Analytics system. The result can be retrieved by sending the job ID to the /jobs endpoint documented below.

For the new WHAPI endpoint, data is available from January 1, 2018.

Example Request 🔗

• New Endpoint
• Old Endpoint

• https://v2.whapi.chartboost.com/metrics/install?dateMin={Minimum date}&dateMax={Maximum date}&userId={Chartboost customer’s user ID}&userSignature={CB customer’s user signature}
  

• https://analytics.chartboost.com/v3/metrics/install?dateMin={Minimum date}&dateMax={Maximum date}&userId={Chartboost customer’s user ID}&userSignature={CB customer’s user signature}
  

Parameters 🔗

Response Fields 🔗

For asynchronous response, a CSV will be returned.

The export installs endpoint will return a JSON object containing a job ID (e.g. {“jobId”: “abbfc348916av461aavb125a“}). This job ID can be used in conjunction with the /jobs endpoint to retrieve the resulting CSV file.

App Analytics grouped by country 🔗

The appcountry endpoint is a specially designed endpoint to return clean analytics data at the app, date, and country level and can also be used on behalf of Chartboost customers by third-party attribution and mediation services that require country-level data.

For the new WHAPI endpoint, data is available from June 16, 2020.

Example Request 🔗

• New Endpoint
• Old Endpoint

• https://v2.whapi.chartboost.com/metrics/appcountry?dateMin={Minimum date}&dateMax={Maximum date}&userId={Chartboost customer’s user ID}&userSignature={CB customer’s user signature}
  

• https://analytics.chartboost.com/v3/metrics/appcountry?dateMin={Minimum date}&dateMax={Maximum date}&userId={Chartboost customer’s user ID}&userSignature={CB customer’s user signature}
  

Parameters 🔗

Response Fields 🔗

Monetization 🔗

For the new WHAPI endpoint, data is available from January 1, 2018.

Parameters 🔗

Response Fields 🔗

Jobs 🔗

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.

Request Fields 🔗

Response Fields 🔗

status=true Synchronous response, JSON result

status=false Synchronous response, CSV result

groupBy=app 🔗

Asynchronous response, CSV result

The endpoint will return a JSON object containing a job ID (e.g. {“jobId”: “abbfc348916av461aavb125a“}). This job id can then be used in conjunction with the /jobs endpoint to retrieve the resulting CSV file.

groupBy=country 🔗

Asynchronous response, CSV result

The endpoint will return a JSON object containing a job ID (e.g. {“jobId”: “abbfc348916av461aavb125a“}). This job id can then be used in conjunction with the /jobs endpoint to retrieve the resulting CSV file.

groupBy=creative 🔗

Asynchronous response, CSV result

The endpoint will return a JSON object containing a job ID (e.g. {“jobId”: “abbfc348916av461aavb125a“}). This job id can then be used in conjunction with the /jobs endpoint to retrieve the resulting CSV file.

Response 🔗

Asynchronous response, CSV result

The endpoint will return a JSON object containing a job ID (e.g. {“jobId”: “abbfc348916av461aavb125a“}). This job id can then be used in conjunction with the /jobs endpoint to retrieve the resulting CSV file.

All Time 🔗

Request Fields 🔗

Response Fields 🔗

category=app Synchronous response, JSON result

category=campaign Synchronous response, JSON result