Analytics API
Before you get started 🔗
api.chartboost.com/v5/analytics
) which uses an OAuth2 standard protocol as opposed to the older HTTP methods. Support for WHAPI (v2.whapi.chartboost.com
) will be sunsetting soon. Any new API endpoints will only be available for version 5 moving forwards.
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
.
- 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
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.
-
https://api.chartboost.com/v5/analytics/jobs/[jobId]
-
https://v2.whapi.chartboost.com/metrics/jobs/[jobId]
-
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 };
-
// 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 } };
- After receiving
GET /campaign
andGET /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
.
Endpoints 🔗
Description | Version 5 Endpoints | v2.whapi.chartboost.com Endpoint |
---|---|---|
Campaign analytics | GET https://api.chartboost.com/v5/analytics/campaign |
https://v2.whapi.chartboost.com/metrics/campaign |
App analytics | GET https://api.chartboost.com/v5/analytics/app |
https://v2.whapi.chartboost.com/metrics/app |
Export installs | GET https://api.chartboost.com/v5/analytics/install |
https://v2.whapi.chartboost.com/metrics/install |
App analytics grouped by country | GET https://api.chartboost.com/v5/analytics/appcountry |
https://v2.whapi.chartboost.com/metrics/appcountry |
Monetization | GET https://api.chartboost.com/v5/analytics/monetization |
https://v2.whapi.chartboost.com/metrics/monetization |
Jobs | GET https://api.chartboost.com/v5/analytics/jobs/[jobId] |
https://v2.whapi.chartboost.com/metrics/jobs/[jobId] |
All Time | GET https://api.chartboost.com/v5/analytics/alltime |
https://v2.whapi.chartboost.com/metrics/alltime |
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.
-
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
andgroupBy=campaign (default), campaign_target, campaign_type, date
- data is available from March 1, 2020 when
timezone=utc
andgroupBy=campaign (default), campaign_target, campaign_type, date
- data is available from June 16, 2020 when
groupBy=target_creative
Request Parameter 🔗
Parameter | Request Type | Required? | Default | Description |
---|---|---|---|---|
aggregate |
String | Optional | Daily | Aggregate the results over time (daily, weekly, monthly) |
campaignId |
String | Optional | N/A | Campaign ID (can be either To Campaign ID or From Campaign ID based on groupBy and role) |
campaignType |
String | Optional | network | Either all , or one or more of the following: network , direct_deal , cross_promo , exchange , helium . Note: If a network is chosen, then the exchange data will automatically be returned. The old WHAPI allows filtering by one network. The new WHAPI allows a list of campaign types to be filtered by. |
dateMin |
String | Required | N/A | The minimum date (YYYY-MM-DD) |
dateMax |
String | Required | N/A | The maximum date (YYYY-MM-DD) |
groupBy |
String | Optional | None | One of the following: country , app , app,creative , target_creative , date , campaign , campaign_target , campaign_type |
platform |
String | Optional | All | Filter by specific platforms (iOS, Google Play, Amazon) |
role |
String | Optional | Both | advertiser , publisher |
adTypeId |
String | Optional | None | Old endpoint: Returns the first ad type id encountered and does not group by ad type id. New endpoint: 1, 4, 5, 7, 8, 9, 10 |
timezone |
String | Optional | PST | UTC / PST |
appID |
String | Optional | None | Filter by one or more app ids |
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" }
-
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 🔗
groupBy = campaign
Synchronous response, JSON result
Parameter | Type | Description |
---|---|---|
adTypeId |
String | 1=interstitial , 2=more_apps , 3=in_play , 4=rewarded_video , 5=video_interstitial , 8=intersitial placement , 9=rewarded placement , 10=banner |
campaign |
String | Campaign name |
campaignId |
String | Campaign ID |
campaignSubType |
String | Campaign subtype |
campaignTarget |
String | Campaign target; always empty string on this groupBy |
campaignType |
String | Campaign type |
clicksDelivered |
Integer | Clicks delivered; 0 for advertisers |
clicksReceived |
Integer | Clicks received; 0 for publishers |
cpcvEarned |
Float | Ratio of money earned from completed video views to completed video views; 0 for advertisers |
cpcvSpent |
Float | Ratio of money spent on completed video views to the number of completed video views; 0 for publishers |
creative |
String | Creative; always empty string on this groupBy |
ctrDelivered |
Float | Click through rate for delivered impressions; 0 for advertisers |
ctrReceived |
Float | Click through rate for received impressions; 0 for publishers |
dt |
String | Date (YYYY-MM-DD) |
ecpmEarned |
Float | Earnings per 1000 impressions; 0 for advertisers |
ecpmSpent |
Float | Cost per 1000 impressions; 0 for publishers |
impressionsDelivered |
Integer | Impressions delivered by the publisher; 0 for advertisers |
impressionsReceived |
Integer | Impressions received by the advertiser; 0 for publishers |
installDelivered |
Integer | Installs delivered; 0 for advertisers |
installRateDelivered |
Float | Install rate; 0 for advertisers |
installRateReceived |
Float | Install rate; 0 for publishers |
installReceived |
Integer | Installs received; 0 for publishers |
moneyEarned |
Float | Money earned; 0 for advertisers |
moneySpent |
Float | Money spent; 0 for publishers |
role |
String | Role: advertiser or publisher |
videoCompletedDelivered |
Integer | Completed video views delivered; 0 for advertisers |
videoCompletedReceived |
Integer | Completed video views received; 0 for publishers |
groupBy = campaign_target
Synchronous response, JSON result
Parameter | Type | Description |
---|---|---|
adTypeId |
String | 1=interstitial , 2=more_apps , 3=in_play , 4=rewarded_video , 5=video_interstitial , 8=intersitial placement , 9=rewarded placement , 10=banner |
campaign |
String | Campaign name |
campaignId |
String | Campaign ID |
campaignSubType |
String | Campaign subtype |
campaignTarget |
String | Campaign target |
campaignType |
String | Campaign type |
clicksDelivered |
Integer | Clicks delivered; 0 for advertisers |
clicksReceived |
Integer | Clicks received; 0 for publishers |
cpcvEarned |
Float | Ratio of money earned from completed video views to completed video views; 0 for advertisers |
cpcvSpent |
Float | Ratio of money spent on completed video views to the number of completed video views; 0 for publishers |
creative |
String | Creative; always empty string on this groupBy |
ctrDelivered |
Float | Click through rate for delivered impressions; 0 for advertisers |
ctrReceived |
Float | Click through rate for received impressions; 0 for publishers |
dt |
String | Date (YYYY-MM-DD) |
ecpmEarned |
Float | Earnings per 1000 impressions; 0 for advertisers |
ecpmSpent |
Float | Cost per 1000 impressions; 0 for publishers |
impressionsDelivered |
Integer | Impressions delivered by the publisher; 0 for advertisers |
impressionsReceived |
Integer | Impressions received by the advertiser; 0 for publishers |
installDelivered |
Integer | Installs delivered; 0 for advertisers |
installRateDelivered |
Float | Install rate; 0 for advertisers |
installRateReceived |
Float | Install rate; 0 for publishers |
installReceived |
Integer | Installs received; 0 for publishers |
moneyEarned |
Float | Money earned; 0 for advertisers |
moneySpent |
Float | Money spent; 0 for publishers |
role |
String | Role: advertiser or publisher |
videoCompletedDelivered |
Integer | Completed video views delivered; 0 for advertisers |
videoCompletedReceived |
Integer | Completed video views received; 0 for publishers |
groupBy = campaign_type
Synchronous response, JSON result
Parameter | Type | Description |
---|---|---|
adTypeId |
String | Ad type ID; always empty string on this groupBy |
campaign |
String | Campaign name; always empty string on this groupBy |
campaignId |
String | Campaign ID; always empty string on this groupBy |
campaignSubType |
String | Campaign subtype |
campaignTarget |
String | Campaign target; always empty string on this groupBy |
campaignType |
String | Campaign type |
clicksDelivered |
Integer | Clicks delivered; 0 for advertisers |
clicksReceived |
Integer | Clicks received; 0 for publishers |
cpcvEarned |
Float | Ratio of money earned from completed video views to completed video views; 0 for advertisers |
cpcvSpent |
Float | Ratio of money spent on completed video views to the number of completed video views; 0 for publishers |
creative |
String | Creative; always empty string on this groupBy |
ctrDelivered |
Float | Click through rate for delivered impressions; 0 for advertisers |
ctrReceived |
Float | Click through rate for received impressions; 0 for publishers |
dt |
String | Date (YYYY-MM-DD) |
ecpmEarned |
Float | Earnings per 1000 impressions; 0 for advertisers |
ecpmSpent |
Float | Cost per 1000 impressions; 0 for publishers |
impressionsDelivered |
Integer | Impressions delivered by the publisher; 0 for advertisers |
impressionsReceived |
Integer | Impressions received by the advertiser; 0 for publishers |
installDelivered |
Integer | Installs delivered; 0 for advertisers |
installRateDelivered |
Float | Install rate; 0 for advertisers |
installRateReceived |
Float | Install rate; 0 for publishers |
installReceived |
Integer | Installs received; 0 for publishers |
moneyEarned |
Float | Money earned; 0 for advertisers |
moneySpent |
Float | Money spent; 0 for publishers |
role |
String | Role: advertiser or publisher |
videoCompletedDelivered |
Integer | Completed video views delivered; 0 for advertisers |
videoCompletedReceived |
Integer | Completed video views received; 0 for publishers |
groupBy = date
Synchronous response, JSON result
Parameter | Type | Description |
---|---|---|
adTypeId |
String | Ad type ID; always empty string on this groupBy |
campaign |
String | Campaign name; always empty string on this groupBy |
campaignId |
String | Campaign ID; always empty string on this groupBy |
campaignSubType |
String | Campaign subtype; always empty string on this groupBy |
campaignTarget |
String | Campaign target; always empty string on this groupBy |
campaignType |
String | Campaign type; always empty string on this groupBy |
clicksDelivered |
Integer | Clicks delivered; 0 for advertisers |
clicksReceived |
Integer | Clicks received; 0 for publishers |
cpcvEarned |
Float | Ratio of money earned from completed video views to completed video views; 0 for advertisers |
cpcvSpent |
Float | Ratio of money spent on completed video views to the number of completed video views; 0 for publishers |
creative |
String | Creative; always empty string on this groupBy |
ctrDelivered |
Float | Click through rate for delivered impressions; 0 for advertisers |
ctrReceived |
Float | Click through rate for received impressions; 0 for publishers |
dt |
String | Date (YYYY-MM-DD) |
ecpmEarned |
Float | Earnings per 1000 impressions; 0 for advertisers |
ecpmSpent |
Float | Cost per 1000 impressions; 0 for publishers |
impressionsDelivered |
Integer | Impressions delivered by the publisher; 0 for advertisers |
impressionsReceived |
Integer | Impressions received by the advertiser; 0 for publishers |
installDelivered |
Integer | Installs delivered; 0 for advertisers |
installRateDelivered |
Float | Install rate; 0 for advertisers |
installRateReceived |
Float | Install rate; 0 for publishers |
installReceived |
Integer | Installs received; 0 for publishers |
moneyEarned |
Float | Money earned; 0 for advertisers |
moneySpent |
Float | Money spent; 0 for publishers |
role |
String | Role: advertiser or publisher; always empty string on this groupBy |
videoCompletedDelivered |
Integer | Completed video views delivered; 0 for advertisers |
videoCompletedReceived |
Integer | Completed video views received; 0 for publishers |
groupBy = target_creative
Synchronous response, JSON result
Parameter | Type | Description |
---|---|---|
app |
String | App ID |
campaign |
String | Campaign name; always empty string on this groupBy |
campaignSubType |
String | Campaign subtype; always empty string on this groupBy |
campaignTarget |
String | Campaign target; always empty string on this groupBy |
campaignType |
String | Campaign type; always empty string on this groupBy |
clicksReceived |
Integer | Clicks received |
cpcvSpent |
Float | Ratio of money spent on completed video views to the number of completed video views |
creative |
String | Creative; always empty string on this groupBy |
ctrReceived |
Float | Click through rate for received impressions |
dt |
String | Date (YYYY-MM-DD) |
ecpmSpent |
Float | Cost per 1000 impressions |
impressionsReceived |
Integer | Impressions received by the advertiser |
installRateReceived |
Float | Install rate |
installReceived |
Integer | Installs received |
moneySpent |
Float | Money spent |
platform |
String | Platform: iOS, Google Play or Amazon |
videoCompletedReceived |
Integer | Completed video views received |
groupBy = app
Asynchronous response, CSV result
The endpoint will return a simple JSON object containing a job ID like
{“jobId”: “abbfc348916av461aavb125a“}
This job id can then be used in conjunction with the
/jobs
endpoint to retrieve the resulting CSV file.
Parameter | Type | Description |
---|---|---|
Ad Type | String | 1=interstitial , 2=more_apps , 3=in_play , 4=rewarded_video , 5=video_interstitial , 8=intersitial placement , 9=rewarded placement , 10=banner |
Campaign Type | String | Campaign Type |
Clicks | Integer | Clicks |
Completed View | Integer | Completed video views |
CTR | Float | Click through rate |
Date | String | Date (YYYY-MM-DD) |
eCPM Earned | Float | Earnings per 1000 impressions |
eCPM Spent | Float | Cost per 1000 impressions |
From App Bundle | String | From app bundle |
From App ID | String | From app ID |
From App Name | String | From app name |
From App Platform | String | From app platform |
From Campaign ID | String | From campaign ID |
From Campaign Name | String | From campaign name |
Impressions | Integer | Impressions |
Installs | Integer | Installs |
IR | Float | Install rate |
Money Earned | Integer | Money earned |
Money Spent | Integer | Money spent |
To App Bundle | String | To app bundle |
To App ID | String | To app id |
To App Name | String | To app name |
To App Platform | String | To app platfrom |
To Campaign ID | String | To campaign ID |
To Campaign Name | String | To campaign name |
groupBy = country
Asynchronous response, CSV result
The endpoint will return a simple JSON object containing a job ID like
{“jobId”: “abbfc348916av461aavb125a“}
This job id can then be used in conjunction with the
/jobs
endpoint to retrieve the resulting CSV file.
Parameter | Type | Description |
---|---|---|
Ad Type | String | 1=interstitial , 2=more_apps , 3=in_play , 4=rewarded_video , 5=video_interstitial , 8=intersitial placement , 9=rewarded placement , 10=banner |
App Bundle | String | App bundle |
App ID | String | App id |
App Name | String | App name |
Campaign ID | String | Campaign ID |
Campaign Name | String | Campaign name |
Campaign Subtype | String | Campaign subtype |
Campaign Type | String | Campaign Type |
Clicks | Integer | Clicks |
Completed Views | Integer | Completed video views |
Country | String | Country |
CTR | Float | Click through rate |
Date | String | Date (YYYY-MM-DD) |
eCPM Earned | Float | Earnings per 1000 impressions |
eCPM Spent | Float | Cost per 1000 impressions |
Impressions | Integer | Impressions |
Installs | Integer | Installs |
IR | Float | Install rate |
Money Earned | Integer | Money earned |
Money Spent | Integer | Money spent |
Platform | String | Platfrom: iOS, Google Play or Amazon |
Role | String | publisher or advertiser |
groupBy = creative
Asynchronous response, CSV result
The endpoint will return a simple JSON object containing a job ID like
{“jobId”: “abbfc348916av461aavb125a“}
This job id can then be used in conjunction with the
/jobs
endpoint to retrieve the resulting CSV file.
Parameter | Type | Description |
---|---|---|
Ad Type | String | 1=interstitial , 2=more_apps , 3=in_play , 4=rewarded_video , 5=video_interstitial , 8=intersitial placement , 9=rewarded placement , 10=banner |
Campaign Type | String | Campaign Type |
Clicks | Integer | Clicks |
Completed View | Integer | Completed video views |
Creative | String | Creative |
CTR | Float | Click through rate |
Date | String | Date (YYYY-MM-DD) |
eCPM Earned | Float | Earnings per 1000 impressions |
eCPM Spent | Float | Cost per 1000 impressions |
From App Bundle | String | From app bundle |
From App ID | String | From app ID |
From App Name | String | From app name |
From App Platform | String | From app platform |
From Campaign ID | String | From campaign ID |
From Campaign Name | String | From campaign name |
Impressions | Integer | Impressions |
Installs | Integer | Installs |
IR | Float | Install rate |
Money Earned | Integer | Money earned |
Money Spent | Integer | Money spent |
Role | String | publisher or advertiser |
To App Bundle | String | To app bundle |
To App ID | String | To app id |
To App Name | String | To app name |
To App Platform | String | To app platfrom |
To Campaign ID | String | To campaign ID |
To Campaign Name | String | To campaign name |
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.
-
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 🔗
Parameter | Request type | Required? | Description | Default |
---|---|---|---|---|
aggregate |
String | Optional | Aggregate the results over time (daily, weekly, monthly) | Daily |
appId |
String | Optional | One or more (comma-separated) app IDs | All |
dateMax |
String | Required | The maximum date (YYYY-MM-DD) | N/A |
dateMin |
String | Required | The minimum date (YYYY-MM-DD) | N/A |
groupBy |
String | Optional | One of the following: app , ad_type , date , ad_location (Publishers only), platform , campaign_type , country |
None |
platform |
String | Optional | Any of the following: iOS, Google Play, Amazon Note: For groupBy=ad_type , the old WHAPI can only accept one platform to filter by. The new WHAPI can accept a list of platforms to filter by. |
All |
role |
String | Optional | advertiser or publisher |
Both |
adTypeId |
String | Optional | Filter by ad type id with one or more of the following: 1, 4, 5, 7, 8, 9, 10 | N/A |
Example Request 🔗
-
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:
Parameter | Description | Returned for… |
---|---|---|
dt |
Date (YYYY-MM-DD) | Everyone |
appId |
Chartboost app ID | Everyone |
app |
App name | Everyone |
appBundleId |
Deprecated | Everyone, not on groupBy=country |
platform |
iOS, Google Play, or Amazon | Everyone |
campaignType |
Campaign Type | Everyone, not on groupBy=country |
eventLocation |
Event Location | Everyone, not on groupBy=country |
ad_type |
1=interstitial , 4=rewarded_video , 5=video_interstitial , 7=prefetch 8=interstitial_placement , 9=rewarded_placement , 10=banner |
Everyone, not on groupBy=date, app, campaign_type, country |
bootups |
Number of times a user launches your app on a device | Everyone, not on groupBy=campaign_type, country |
uniques |
Number of unique users | Everyone, not on groupBy=campaign_type, country |
impressions |
Impressions | Everyone, not on groupBy=campaign_type, country |
impressionsDelivered |
Impressions delivered by the publisher | Publishers, not on groupBy=country |
impressionsReceived |
Impressions received by the advertiser | Advertisers, not on groupBy=country |
money |
Total money earned for publishers, spent for advertisers | Everyone, only on groupBy=country |
moneyEarned |
Total money earned by publisher | Publishers |
moneySpent |
Total money spent by advertisers | Advertisers |
ecpm |
Earnings per 1,000 impressions | Everyone, only on groupBy=country |
ecpmEarned |
Earnings per 1,000 impressions | Publishers, not on groupBy=country |
ecpmSpent |
Cost per 1,000 impressions | Advertisers, not on groupBy=country |
cpcv |
Ratio of money earned from completed video views to the number of completed video views | Everyone, only on groupBy=country |
cpcvEarned |
Ratio of money earned from completed video views to the number of completed video views | Publishers, not on groupBy=country |
cpcvSpent |
Ratio of money spent on completed video views to the number of completed video views | Advertisers, not on groupBy=country |
clicks |
Total number of clicks | Everyone, only on groupBy=country |
clicksDelivered |
Clicks delivered to publishers | Publishers, not on groupBy=country |
clicksReceived |
Clicks received by advertisers | Advertisers, not on groupBy=country |
installs |
Converted installs | Everyone, only on groupBy=country |
allInstalls |
Number of total installs accrued regardless of source (Chartboost or otherwise) | Everyone |
installDelivered |
Installs delivered to publisher | Publishers, not on groupBy=country |
installReceived |
Installs received by advertiser | Advertisers, not on groupBy=country |
ctr | Clickthrough rate | Everyone, only on groupBy=country |
ctrlDelivered |
Clickthrough rate for delivered impressions | Publishers, not on groupBy=country |
ctrReceived |
Clickthrough rate for received impressions | Advertisers, not on groupBy=country |
videoCompleted |
Total completed video | Everyone, only on groupBy=country |
videoCompletedDelivered |
Completed video views delivered | Publishers, not on groupBy=country |
VideoCompletedReceived |
Completed video views received | Advertisers, not on groupBy=country |
installRate |
Install rate | Everyone, only on groupBy=country |
installRateDelivered |
Install rate delivered | Publishers, not on groupBy=country |
installRateReceived |
Install rate received | Advertisers, not on groupBy=country |
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.
-
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 🔗
Parameter | Request type | Required? | Description | Default |
---|---|---|---|---|
campaignIds |
String | Optional | One or more (comma-separated) campaign IDs | All campaigns |
campaignType |
String | Optional | Campaign type. One or more of the following: network , direct_deal , cross_promo , exchange , helium |
All |
appIds |
String | Optional | Filter by App Id | N/A |
dateMax |
String | Required | The maximum date (YYYY-MM-DD) | N/A |
dateMin |
String | Required | The minimum date (YYYY-MM-DD) | N/A |
platform |
String | Optional | Any of the following: iOS, Google Play, Amazon | All |
role |
String | Optional | advertiser or publisher |
Both |
adTypeId |
String | Optional | Filter by Ad Type Id. One or more of the following: 1, 4, 5, 7, 8, 9, 10 | None |
Example Request 🔗
-
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.
Parameter | Description | Returned for… |
---|---|---|
Ad Type | 1=interstitial, 4=rewarded video, 5=video interstitial, 7=prefetch 8=intersitial placement, 9=rewarded placement, 10=banner | Everyone |
Country | Two-letter country code of device | Everyone |
Click Timestamp | Date & time (DD-MM-YYYY HH:MM:SS) | Everyone |
Date | Date & time (DD-MM-YYYY HH:MM:SS) | Everyone |
From App Bundle | Publishing app bundle ID | Everyone |
From App ID | Publishing app ID | Everyone |
From App Name | Publishing app name | Everyone |
From App Platform | Publishing app platform | Everyone |
From Campaign ID | Publishing campaign ID | Publishers |
From Campaign Name | Publishing campaign name | Publishers |
From Campaign Type | Campaign type. One or more of the following: network , direct_deal , cross_promo , exchange , helium |
Publishers |
To App Bundle | Advertising app bundle ID | Everyone |
To App ID | Advertising app ID | Everyone |
To App Name | Advertising app name | Everyone |
To App Platform | App platform. Any of the following: iOS, Google Play, Amazon | Everyone |
To Campaign ID | Advertising campaign ID | Advertisers |
To Campaign Name | Advertising campaign name | Advertisers |
To Campaign Target | Advertising campaign target ID | Everyone |
To Campaign Type | Campaign type. One or more of the following: network , direct_deal , cross_promo , exchange , helium |
Advertisers |
UUID | Device Universal Unique Identifier (if available) | Everyone (Publisher only if Behavioral Targeting is disabled) |
IFA | iOS Identifier for Advertisers (if iOS 10 Limit Ad Tracking is disabled) | Everyone (Publisher only if Behavioral Targeting is disabled) |
MAC | MAC address (Deprecated; nothing will be returned) | N/A |
GAID | Google Advertising ID | Everyone (Publisher only if Behavioral Targeting is disabled) |
Model | Device model | Everyone |
OS | Device operating system | Everyone |
Cost Type | Advertising bid type Learn more about bid types | Everyone |
Cost Value | Advertising bid amount | Everyone |
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.
-
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.
campaignType
field, as the API will automatically return results for network
.country
to retrieve app
, country
, and ad_type data
.adLocation
sent with empty ""
string value via SDK are aggregated under Default
.Request Parameters 🔗
Parameter | Request Type | Required? | Description | Default |
---|---|---|---|---|
appIds |
String | Optional | One or more (comma-separated) app IDs | All apps |
dateMin |
String | Required | The minimum date (YYYY-MM-DD) | N/A |
dateMax |
String | Required | The maximum date (YYYY-MM-DD) | N/A |
campaignType |
String | Optional | Campaign type. One or more of the following: network , direct_deal , cross_promo , exchange , helium |
network |
adTypeIds |
String | Optional | One or more (comma-separated) ad type IDs: 1,4,5,7,8,9,10 | N/A |
role |
String | Optional | advertiser or publisher |
publisher |
timezone |
String | Optional | utc or pst |
utc |
adLocation |
String | Optional | Filter by platform. One or more of the following: iOS, Google Play, Amazon. Case #1: (adLocation=\ shows results aggregated by each adLocation presented ONLY for the specified adLocation(s). Information for any adLocation(s) is only available if the adLocation(s) is one of the Top 100 adLocations used by the Publisher App. No data is returned for the remaining adLocation(s). Case #2: (adLocation='all') shows results broken down by the Top 100 adLocation(s) for a Publisher App with the remaining data being aggregated under adLocation='Default' Case #3: (adLocation= empty or not-passed) aggregates all data under adLocation='overall' . No breakdown by adLocation is provided. |
see case #3 |
adLocation
values must cross a small threshold of activity (generally around 10 different ad creatives displayed), otherwise they will not be broken out and instead aggregated under Default
.
Example Request 🔗
-
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 🔗
Parameter | Description | Returned for… |
---|---|---|
adLocation |
The location of the ad being published in the app. Advertisers will see default in the response field. |
Everyone |
adType |
1=Interstitial Static; 4=Rewarded Video; 5=Interstitial Video; 7= Prefetch; 8= Unified Interstitial; 9= Unified Rewarded; 10= Banner | Everyone |
app |
App name | Everyone |
appId |
App ID | Everyone |
campaignType |
Campaign type. One or more of the following: network , direct_deal , cross_promo , exchange , helium |
Everyone |
clicksDelivered |
Clicks delivered to publishers | Publishers |
clicksReceived |
Clicks received by advertisers | Advertisers |
CountryCode |
Two-letter country code, or “unknown” | Everyone |
cpcvEarned |
Ratio of money earned from completed video views to the number of completed video views | Publishers |
cpcvSpent |
Ratio of money spent on completed video views to the number of completed video views | Advertisers |
ctrDelivered |
Click-through rate delivered to publishers | Publishers |
ctrReceived |
Click-through rate received by advertisers | Advertisers |
dt |
Date (YYYY-MM-DD) | Everyone |
ecpmEarned |
Earnings per 1000 impressions | Publishers |
ecpmSpent |
Cost per 1000 impressions | Advertisers |
impressionsDelivered |
Impressions delivered to publisher | Publishers |
impressionsReceived |
Impressions received by advertiser | Advertisers |
installRateDelivered |
Install rate delivered to publisher | Publishers |
InstallRateReceived |
Install rate received by advertiser | Advertisers |
installsDelivered |
Installs delivered to publisher | Publishers |
installsReceived |
Installs received by advertiser | Advertisers |
moneyEarned |
Money earned | Publishers |
moneySpent |
Money spent | Advertisers |
platform |
iOS, Google Play, or Amazon | Everyone |
videoCompletedDelivered |
Completed video views delivered to publisher | Publishers |
videoCompletedReceived |
Completed video views received by advertiser | Advertisers |
Monetization 🔗
-
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 🔗
Parameter | Request Type | Required? | Description | Default |
---|---|---|---|---|
appIds |
String | Optional | One or more (comma-separated) app IDs | All apps |
dateMin |
String | Required | The minimum date (YYYY-MM-DD) | N/A |
dateMax |
String | Required | The maximum date (YYYY-MM-DD) | N/A |
role |
String | Optional | advertiser or publisher |
advertiser |
Example Request 🔗
-
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 🔗
Parameter | Description | Returned for… |
---|---|---|
dt |
Date (YYYY-MM-DD) | Everyone |
app_id |
App ID | Everyone |
ad_spend |
The total amount of money spent on the last day of the reporting period (Today) [d0]. | Advertisers |
ad_spend_relative |
The relative change in ad spending from the first day to the previous day [d1]. , expressed as a percentage. | Advertisers |
ad_spend_d1 |
Money spent on the second day of the reporting period (Yesterday) [d1]. | Advertisers |
ad_spend_d1_relative |
The relative change in ad spending on the second day of the reporting period (yesterday) compared to the same day of the previous week (7 days prior). | Advertisers |
ad_spend_d7_sum |
The total amount of money spent over the last 7 days, starting from the current day. | Advertisers |
ad_spend_d7_sum_relative |
The relative change in the total ad spending over the last 7 days, starting from yesterday, compared to the total ad spending during the same days of the previous week. | Advertisers |
ad_spend_d28_sum |
The total amount of money spent over the last 28 days, starting from the current day. | Advertisers |
ad_spend_d28_sum_relative |
The relative change in the total ad spending over the last 28 days, starting from yesterday, compared to the total ad spending during the same days of the previous month (28 days prior to the last day of the current 28-day period). | Advertisers |
impressions |
The total amount of impressions on the last day of the reporting period (Today). | Everyone |
impressions_relative |
The relative change in impressions from the first day to the previous day [d1] , expressed as a percentage. | Everyone |
impressions_d7_sum |
The total number of ad impressions over the last 7 days, starting from the current day. | Everyone |
impressions_d7_sum_relative |
The relative change in the total ad impressions over the last 7 days, starting from yesterday, compared to the total impressions during the same days of the previous week (7 days prior to the last day of the current 7-day period). | Everyone |
revenue |
The total amount of money earned on the last day of the reporting period (Today) [d0]. | Publishers |
revenue_relative |
The relative change in money earned on the second day of the reporting period (yesterday) compared to the same day of the previous week (7 days prior). | Publishers |
revenue_d1 |
Money earned on the second day of the reporting period (Yesterday) [d1]. | Publishers |
revenue_d1_relative |
The relative change in money earned on the second day of the reporting period (yesterday) compared to the same day of the previous week (7 days prior). | Publishers |
revenue_d7_sum |
The total amount of money earned over the last 7 days, starting from the current day. | Publishers |
revenue_d7_sum_relative |
The relative change in the money earned over the last 7 days, starting from yesterday, compared to the total ad spending during the same days of the previous week. | Publishers |
revenue_d28_sum |
The total amount of money earned over the last 28 days, starting from the current day. | Publishers |
revenue_d28_sum_relative |
The relative change in the total money earned over the last 28 days, starting from yesterday, compared to the total ad spending during the same days of the previous month (28 days prior to the last day of the current 28-day period). | Publishers |
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.
-
GET https://api.chartboost.com/v5/analytics/jobs/[jobId]
-
https://v2.whapi.chartboost.com/metrics/jobs/[jobId]
Request Parameters 🔗
Parameter | Request Type | Requirement | Default | Description |
---|---|---|---|---|
status |
String | Required | false | Whether the job’s status is needed. Enter true for yes or false for no. |
csv_format |
String | Required | TSV | The format of the resulting file. One of the following: CSV , TSV |
Example Request 🔗
-
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
Parameter | Type | Description |
---|---|---|
status | String | Any of: not found , failed, pending , expired , created |
message | String | Extra information on the status, not returned if status=created |
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.
Parameter | Type | Description |
---|---|---|
Date | String | Date (YYYY-MM-DD) |
To Campaign Name | String | To campaign name |
To Campaign ID | String | To campaign ID |
To App Name | String | To app name |
To App ID | String | To app id |
To App Bundle | String | To app bundle |
To App Platform | String | To app platfrom |
From Campaign Name | String | From campaign name |
From Campaign ID | String | From campaign ID |
From App Name | String | From app name |
From App ID | String | From app ID |
From App Bundle | String | From app bundle |
From App Platform | String | From app platform |
Campaign Type | String | Campaign Type |
Ad Type | String | 1=interstitial , 2=more_apps , 3=in_play , 4=rewarded_video , 5=video_interstitial , 8=intersitial placement , 9=rewarded placement , 10=banner |
Impressions | Integer | Impressions |
Clicks | Integer | Clicks |
Installs | Integer | Installs |
CTR | Float | Click through rate |
IR | Float | Install rate |
Money Earned | Integer | Money earned |
eCPM Earned | Float | Earnings per 1000 impressions |
Money Spent | Integer | Money spent |
eCPM Spent | Float | Cost per 1000 impressions |
Completed View | Integer | Completed video views |
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.
Parameter | Type | Description |
---|---|---|
Date | String | Date (YYYY-MM-DD) |
Country | String | Country |
Campaign Name | String | Campaign name |
Campaign ID | String | Campaign ID |
Campaign Type | String | Campaign Type |
Campaign Subtype | String | Campaign subtype |
App Name | String | App name |
App ID | String | App id |
App Bundle | String | App bundle |
Platform | String | Platfrom: iOS, Google Play or Amazon |
Role | String | publisher or advertiser |
Ad Type | String | 1=interstitial , 2=more_apps , 3=in_play , 4=rewarded_video , 5=video_interstitial , 8=intersitial placement , 9=rewarded placement , 10=banner |
Impressions | Integer | Impressions |
Clicks | Integer | Clicks |
Installs | Integer | Installs |
Completed Views | Integer | Completed video views |
CTR | Float | Click through rate |
IR | Float | Install rate |
Money Earned | Integer | Money earned |
eCPM Earned | Float | Earnings per 1000 impressions |
Money Spent | Integer | Money spent |
eCPM Spent | Float | Cost per 1000 impressions |
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.
Parameter | Type | Description |
---|---|---|
Date | String | Date (YYYY-MM-DD) |
To Campaign Name | String | To campaign name |
To Campaign ID | String | To campaign ID |
To App Name | String | To app name |
To App ID | String | To app id |
To App Bundle | String | To app bundle |
To App Platform | String | To app platfrom |
From Campaign Name | String | From campaign name |
From Campaign ID | String | From campaign ID |
From App Name | String | From app name |
From App ID | String | From app ID |
From App Bundle | String | From app bundle |
From App Platform | String | From app platform |
Campaign Type | String | Campaign Type |
Creative | String | Creative |
Role | String | publisher or advertiser |
Ad Type | String | 1=interstitial , 2=more_apps , 3=in_play , 4=rewarded_video , 5=video_interstitial , 8=intersitial placement , 9=rewarded placement , 10=banner |
Impressions | Integer | Impressions |
Clicks | Integer | Clicks |
Installs | Integer | Installs |
CTR | Float | Click through rate |
IR | Float | Install rate |
Money Earned | Integer | Money earned |
eCPM Earned | Float | Earnings per 1000 impressions |
Money Spent | Integer | Money spent |
eCPM Spent | Float | Cost per 1000 impressions |
Completed View | Integer | Completed video views |
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.
Parameter | Type | Description |
---|---|---|
Date | String | Date (YYYY-MM-DD) |
Click Timestamp | String | Timestamp |
From Campaign Name | String | From campaign name |
From Campaign ID | String | From campaign ID |
From Campaign Type | String | From campaign type |
From App Name | String | From app name |
From App ID | String | From app ID |
From App Bundle | String | From app bundle |
From App Platform | String | From app platform |
To Campaign Name | String | To campaign name |
To Campaign ID | String | To campaign ID |
To Campaign Type | String | To campaign type |
To App Name | String | To app name |
To App ID | String | To app id |
To App Bundle | String | To app bundle |
To App Platform | String | To app platfrom |
To Campaign Target | String | To campaign target |
UUID | String | UUID |
IFA | String | ID for advertisers |
MAC | String | MAC address |
GAID | String | Google Advertising ID |
Model | String | Device model |
OS | String | Device OS |
Country | String | Country |
Cost Type | String | Cost Type |
Cost Value | Float | Cost Value |
Ad Type | String | 1=interstitial , 2=more_apps , 3=in_play , 4=rewarded_video , 5=video_interstitial , 8=intersitial placement , 9=rewarded placement , 10=banner |
All Time 🔗
-
GET https://api.chartboost.com/v5/analytics/alltime
-
https://v2.whapi.chartboost.com/metrics/alltime
Request Fields 🔗
Parameter | Request Type | Requirement | Default | Description |
---|---|---|---|---|
category |
String | Optional | app |
One of the following: app , campaign |
Example Request 🔗
-
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
Parameter | Type | Description |
---|---|---|
appId |
String | App ID |
appName |
String | App name |
totalInstalls |
Integer | Total Installs |
revenue |
Float | Revenue |
expenditure |
Float | Expenditure |
category=campaign
Synchronous response, JSON result
Parameter | Type | Description |
---|---|---|
campaignId |
String | Campaign ID |
campaignName |
String | Campaign name |
revenue |
Float | Revenue |
expenditure |
Float | Expenditure |