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.

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

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

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 🔗

Analytics 🔗

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

Parameter Description Returned for…
dt Date (YYYY-MM-DD) Everyone
role Role: advertiser or publisher Everyone

Not on groupBy=target_creative
campaignId Campaign ID Everyone
campaign Campaign name Everyone
campaignType Campaign type Everyone
campaignSubType Campaign subtype Everyone
campaignTarget Campaign target Everyone
creative Creative Advertisers

Only on groupBy=target_creative
adTypeId 1=interstitial, 2=more_apps, 3=in_play, 4=rewarded_video, 5=video_interstitial, 10=banner, 11=native Everyone

Not on groupBy=target_creative
app App ID Advertisers

Only on groupBy=target_creative
platform iOS, Google Play or Amazon Advertisers

Only on groupBy=target_creative
impressionsDelivered Impressions delivered by the publisher Publishers

Not on groupBy=target_creative
impressionsReceived Impressions received by the advertiser Advertisers
moneyEarned Money earned Publishers

Not on groupBy=target_creative
moneySpent Money spent Advertisers
ecpmEarned Earnings per 1,000 impressions Publishers

Not on groupBy=target_creative
ecpmSpent Cost per 1,000 impressions Advertisers
cpcvSpent Ratio of money spent on completed video views to the number of completed video views Publishers

Not on groupBy=target_creative
cpcvEarned Ratio of money earned from completed video views to completed video views Advertisers
clicksDelivered Clicks delivered Publishers

Not on groupBy=target_creative
clicksReceived Clicks received Advertisers
installDelivered Installs delivered Publishers

Not on groupBy=target_creative
InstallReceived Installs Advertisers
ctrDelivered Click through rate for delivered impressions Publishers

Not on groupBy=target_creative
ctrReceived Click through rate for received impressions Advertisers
videoCompletedDelivered Completed video views delivered Publishers

Not on groupBy=target_creative
videoCompletedReceived Completed video views received Advertisers
installRateDelivered Install rate Publishers

Not on groupBy=target_creative
installRateReceived Install rate Advertisers
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:

Parameter Description Returned for…
Date Date (YYYY-MM-DD) Everyone
To Campaign Name To campaign name Everyone
To Campaign ID To campaign ID Everyone
To App Name To app name Everyone
To App Id To app id Everyone
To App Bundle To app bundle Everyone
To App Platform To app platform Everyone
From Campaign Name From campaign name Everyone
From Campaign ID From campaign ID Everyone
From App Name From app name Everyone
From App ID From app ID Everyone
From App Bundle From app bundle Everyone
From App Platform From app platform Everyone
Campaign Type Campaign Type Everyone
Creative Creative Everyone

Only on groupBy = app,creative
Role Advertiser or publisher Everyone

Only on groupBy = country, creative
Ad Type 1=interstitial, 4=rewarded_video, 5=video_interstitial, 7=prefetch, 8=intersitial_placement, 9=rewarded_placement, 10=banner Everyone
Impressions Impressions Everyone
Clicks Clicks Everyone
Installs Installs Everyone
Completed Views Completed video views Everyone

Only on groupBy = country
CTR Click through rate Everyone
IR Install rate Everyone
Money Earned Money earned Everyone
eCPM Earned Earnings per 1000 impressions Everyone
Money Spent Money spent Everyone
eCPM Spent Cost per 1000 impressions Everyone
Completed Views Completed video views Only on groupBy = app,creative

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.

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

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