Analytics API

Before you get started 🔗

Authentication 🔗

Version 5 API 🔗

To start using the version 5 API (api.chartboost.com/v5/analytics), complete the API Access & Authentication process. You will not be able to access your analytics programmatically until this step is completed.

WHAPI 🔗

Your account’s user ID and user signature are required to authenticate your API request for v2.whapi.chartboost.com.

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 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 endpoints, all requests should be made via HTTPS.

• Version 5 Endpoint
• WHAPI Endpoint

• https://api.chartboost.com/v5/analytics/jobs/[jobId]
  

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

• Version 5 Example Request
• WHAPI Example Request

• GET https://api.chartboost.com/v5/analytics/campaign HTTP/1.1
  Host: api.chartboost.com
  Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW
  Content-Type: application/json;charset=UTF-8
  
  {
    "dateMin": "2024-01-01",
    "dateMax": "2024-03-01",
    "groupBy": "app,creative"
  }
  

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

• Version 5 Example Response
• WHAPI Example Response

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

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

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.

• Version 5
• WHAPI

• GET https://api.chartboost.com/v5/analytics/campaign
  

• https://v2.whapi.chartboost.com/metrics/campaign
  

For version 5 and 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

Request Parameter 🔗

Example Request 🔗

• Version 5
• WHAPI

• GET https://api.chartboost.com/v5/analytics/campaign HTTP/1.1
  Host: api.chartboost.com
  Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW
  Content-Type: application/json;charset=UTF-8
  
  {
  "dateMin": "2024-01-01",
  "dateMax": "2024-03-01"
  }
  

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

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.

• Version 5
• WHAPI

• GET https://api.chartboost.com/v5/analytics/app HTTP/1.1
  Host: api.chartboost.com
  Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW
  Content-Type: application/json;charset=UTF-8
  
  {
  "dateMin": "2024-01-01",
  "dateMax": "2024-03-01"
  }
  

• https://v2.whapi.chartboost.com/metrics/app
  

For the version 5 and 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

Request Parameters 🔗

Example Request 🔗

• Version 5
• WHAPI

• GET https://api.chartboost.com/v5/analytics/app HTTP/1.1
  Host: api.chartboost.com
  Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW
  Content-Type: application/json;charset=UTF-8
  
  {
  "dateMin": "2024-01-01",
  "dateMax": "2024-03-01"
  }
  

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

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.

• Version 5
• WHAPI

• GET https://api.chartboost.com/v5/analytics/install
  

• https://v2.whapi.chartboost.com/metrics/install
  

For the version 5 and WHAPI endpoint, data is available from January 1, 2018.

Request Parameters 🔗

Example Request 🔗

• Version 5
• WHAPI

• GET https://api.chartboost.com/v5/analytics/install HTTP/1.1
  Host: api.chartboost.com
  Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW
  Content-Type: application/json;charset=UTF-8
  
  {
    "dateMin": "2024-01-01",
    "dateMax": "2024-03-01"
  }
  

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

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.

• Version 5
• WHAPI

• GET https://api.chartboost.com/v5/analytics/appcountry
  

• https://v2.whapi.chartboost.com/metrics/appcountry
  

For the version 5 and WHAPI endpoint, data is available from June 16, 2020.

Request Parameters 🔗

Example Request 🔗

• Version 5
• WHAPI

• GET https://api.chartboost.com/v5/analytics/appcountry HTTP/1.1
  Host: api.chartboost.com
  Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW
  Content-Type: application/json;charset=UTF-8
  
  {
    "dateMin": "2024-01-01",
    "dateMax": "2024-03-01"
  }
  

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

Response Fields 🔗

Monetization 🔗

• Version 5
• WHAPI

• GET https://api.chartboost.com/v5/analytics/monetization
  

• https://v2.whapi.chartboost.com/metrics/monetization
  

For the version 5 and WHAPI endpoint, data is available from January 1, 2018.

Request Parameters 🔗

Example Request 🔗

• Version 5
• WHAPI

• GET https://api.chartboost.com/v5/analytics/monetization HTTP/1.1
  Host: api.chartboost.com
  Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW
  Content-Type: application/json;charset=UTF-8
  
  {
    "dateMin": "2024-01-01",
    "dateMax": "2024-03-01"
  }
  

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

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.

• Version 5
• WHAPI

• GET https://api.chartboost.com/v5/analytics/jobs/[jobId]
  

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

Request Parameters 🔗

Example Request 🔗

• Version 5
• WHAPI

• GET https://api.chartboost.com/v5/analytics/jobs HTTP/1.1
  Host: api.chartboost.com
  Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW
  Content-Type: application/json;charset=UTF-8
  
  {
    "status": "true",
    "csv_format": "CSV"
  }
  

• https://v2.whapi.chartboost.com/metrics/jobs?status={true or false}&csv_format={CSV or TSV}&userId={Chartboost customer’s user ID}&userSignature={CB customer’s user signature}
  

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 🔗

• Version 5

• GET https://api.chartboost.com/v5/analytics/alltime
  

Request Fields 🔗

Example Request 🔗

• Version 5
• WHAPI

• GET https://api.chartboost.com/v5/analytics/alltime HTTP/1.1
  Host: api.chartboost.com
  Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW
  Content-Type: application/json;charset=UTF-8
  

• https://v2.whapi.chartboost.com/metrics/alltime?userId={Chartboost customer’s user ID}&userSignature={CB customer’s user signature}
  

Response Fields 🔗

category=app Synchronous response, JSON result

category=campaign Synchronous response, JSON result