Analytics Methods

The campaign analytics endpoint provides detailed reports that can be grouped by either app or creative. Be advised that when specifying a groupBy field, a job ID will be returned by the Queued Analytics system, as detailed in the “Before you begin” section.
HTTP method GET
Endpoint https://analytics.chartboost.com/v3/metrics/campaign
Example Request https://analytics.chartboost.com/v3/metrics/campaign?dateMin={{Minimum date}}&dateMax={{Maximum date}}&userId={{Chartboost customer’s user ID}}&userSignature={{CB customer’s user signature}}
Parameters
Parameter Request Type Required? Description Default
aggregate String Optional Aggregate the results over time (daily, weekly, monthly) Daily
campaignId String Optional Campaign ID (can be either To Campaign ID or From Campaign ID based on groupBy and role) N/A
campaignType String Optional network, cross_promo network
dateMin String Required The minimum date (YYYY-MM-DD) N/A
dateMax String Required The maximum date (YYYY-MM-DD) N/A
groupBy String Optional One of the following: 'country' 'app' 'app,creative' 'target_creative' 'date' 'campaign' 'campaign_target' 'campaign_type' None
platform String Optional Filter by specific platforms (iOS, Google Play, Amazon) All
role String Optional advertiser or publisher Both
 
Response Fields
Parameter Description Returned for…
adTypeId 1 = interstitial 2 = more_apps 3 = in_play 4 = rewarded_video 5 = video_interstitial 10 = banner Everyone
app App name Everyone
campaign Campaign name Everyone
campaignId Campaign ID (can be either To Campaign ID or From Campaign ID based on groupBy and role) Everyone
campaignTarget Campaign target name (only returned when grouping by campaign_target) Advertisers
campaignSubType user_acquisition Everyone
clicksDelivered Clicks delivered Publishers
clicksReceived Clicks received Advertisers
cpcvEarned Ratio of money earned from completed video views to completed video views Publishers
cpcvSpent Ratio of money spent on completed video views to number of completed video views Advertisers
creative Advertised creative name (only returned when grouping by creative) Advertisers
ctrDelivered Clickthrough rate for delivered impressions Publishers
ctrReceived Clickthrough rate for received impressions Advertisers
dt Date (YYYY-MM-DD) Everyone
ecpmEarned Earnings per 1,000 impressions Publishers
ecpmSpent Cost per 1,000 impressions Advertisers
impressionsDelivered Impressions delivered by the publisher Publishers
impressionsReceived Impressions received by the advertiser Advertisers
installDelivered Installs delivered Publishers
installRateDelivered Install rate Publishers
installRateReceived Install rate Advertisers
installReceived Installs Advertisers
moneyEarned Money earned Publishers
moneySpent Money spent Advertisers
videoCompletedDelivered Completed video views delivered Publishers
videoCompletedReceived Completed video views received Advertisers
  ▲ Back to top
The app analytics endpoint provides detailed reports that can be grouped by app, ad type, or ad location.
HTTP method GET
Endpoint https://analytics.chartboost.com/v3/metrics/app
Example Request https://analytics.chartboost.com/v3/metrics/app?dateMin={{Minimum date}}&dateMax={{Maximum date}}&userId={{Chartboost customer’s user ID}}&userSignature={{CB customer’s user signature}}
Parameters
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,app, date, ad_location (Publishers only), platform, campaign_type None
platform String Optional Any of the following: iOS, Google Play, Amazon All
role String Optional advertiser or publisher Both
 
Response Fields
Parameter Description Returned for…
ad_type Creative ad type Learn more about ad types ▶ Everyone, only when groupBy=ad_type,app
allInstalls Number of total installs accrued regardless of source (Chartboost or otherwise) Everyone
app App name Everyone
appBundleId No longer sent; user will see Deprecated in reports Everyone
appId Chartboost app ID Everyone
bootups Number of times a user launches your app on a device Everyone
campaignType network, cross_promo Everyone, only when groupBy=campaignType
clicksDelivered Clicks delivered Publishers
clicksReceived Clicks received Advertisers
cpcvEarned Ratio of money earned from completed video views to completed video views Publishers
cpcvSpent Ratio of money spent on completed video views to number of completed video views Advertisers
ctrDelivered Clickthrough rate for delivered impressions Publishers
ctrReceived Clickthrough rate for received impressions Advertisers
dt Date (YYYY-MM-DD) Everyone
ecpmEarned Earnings per 1,000 impressions Publishers
ecpmSpent Cost per 1,000 impressions Advertisers
eventLocation The Chartboost named location of the ad being published in the app. Advertisers will see default in the response field. Everyone
impressionsDelivered Impressions delivered by the publisher Publishers
impressionsReceived Impressions received by the advertiser Advertisers
installDelivered Installs delivered Publishers
installRateDelivered Install rate Publishers
installRateReceived Install rate Advertisers
installReceived Installs Advertisers
moneyEarned Money earned Publishers
moneySpent Money spent Advertisers
platform iOS, Google Play, or Amazon Everyone
uniques Number of unique devices that booted up the app Everyone
videoCompletedDelivered Completed video views delivered Publishers
videoCompletedReceived Completed video views received Advertisers
  ▲ Back to top
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, as detailed in the “Before you begin” section.
HTTP method GET
Endpoint https://analytics.chartboost.com/v3/metrics/install
Example Request https://analytics.chartboost.com/v3/metrics/install?dateMin={{Minimum date}}&dateMax={{Maximum date}}&userId={{Chartboost customer’s user ID}}&userSignature={{CB customer’s user signature}}
Parameters
Parameter Request type Required? Description Default
campaignIds String Optional One or more (comma-separated) campaign IDs All campaigns
campaignType String Optional network, cross_promo All
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
 
Response Fields
Parameter Description Returned for…
Ad Type Creative ad type Learn more about ad types ▶ Everyone
Click Timestamp Date & time (DD-MM-YYYY HH:MM:SS) Everyone
Cost Type Advertising bid type Learn more about bid types ▶ Everyone
Cost Value Advertising bid amount Everyone
Country Two-letter country code of device 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 Campaign ID Publishing campaign ID Publishers
From Campaign Name Publishing campaign name Publishers
From Campaign Type network, cross_promo Publishers
GAID Google Advertising ID 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) N/A
Model Device model Everyone
OS Device operating system Everyone
To App Bundle Advertising app bundle ID Everyone
To App ID Advertising app ID Everyone
To App Name Advertising app name 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 network, cross_promo Advertisers
UUID Device Universal Unique Identifier (if available) Everyone (Publisher only if Behavioral Targeting is disabled)
  ▲ Back to top
In addition to the endpoints you’ll find on the dashboard’s API Explorer page, we’ve built one specially designed to return clean analytics data at the app, date, and country level. This endpoint can also be used on behalf of Chartboost customers by third-party attribution and mediation services that require country-level data.
You can expect the full data for a previous calendar day to be available 9 hours after that date is completed in most cases. For example, you can expect that the data for a day ending 0:00 AM PST (7:00 AM UTC) will be completely available after 9:00 AM PST (4:00PM UTC).
When you use the App analytics grouped by country the data is limited to the past 40 days.
Note for mediation networks: We strongly recommend that you omit the campaignType field, as the API will automatically return results for network.
Please note that there might be a discrepancy between app and campaign endpoints and your dashboard analytics. Use the campaign endpoint and group by country to retrieve app, country, and ad_type data.
While data returned by this endpoint is typically only 1-3 hours delayed, in extreme cases it may take up to 9 hours after a day has ended for that day’s complete data to become available to this API.
By default, data from this API segments calendar days by UTC time.
Any adLocation sent with empty "" string value via SDK are aggregated under Default.
HTTP method GET
Endpoint https://analytics.chartboost.com/v3/metrics/appcountry
Example Request https://analytics.chartboost.com/v3/metrics/appcountry?dateMin={{Minimum date}}&dateMax={{Maximum date}}&userId={{Chartboost customer’s user ID}}&userSignature={{CB customer’s user signature}}
Parameters
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 network or cross_promo or both (comma-separated) network
adTypeIds String Optional One or more (comma-separated) ad type IDs: 1 = interstitial, 3 = in_play, 4 = rewarded_video, 5 = video_interstitial, 10 = banner 1,4,5,10
role String Optional advertiser or publisher publisher
timezone String Optional utc or pst utc
adLocation String Optional One or more (comma-separated) adLocations
    • Case #1: (adLocation=<value which is not 'all'>) shows results aggregated by each adLocation presented for 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, for example), otherwise they will not be broken out and instead aggregated under Default.
 
Response Fields
Parameter Description Returned for…
adLocation The Chartboost named location of the ad being published in the app. Advertisers will see default in the response field. Everyone
adType interstitial, rewarded_video, video_interstitial, banner Everyone
app App name Everyone
campaignType network, cross_promo Everyone
clicksDelivered Clicks Publishers
clicksReceived Clicks Advertisers
countryCode Two-letter country code, or “unknown” Everyone
cpcvEarned Ratio of money earned from completed video views to completed video views Publishers
cpcvSpent Ratio of money spent on completed video views to number of completed video views Advertisers
ctrDelivered Click-through rate Publishers
ctrReceived Click-through rate Advertisers
dt Date (YYYY-MM-DD) Everyone
ecpmEarned Earnings per 1000 impressions Publishers
ecpmSpent Cost per 1000 impressions Advertisers
impressionsDelivered Impressions Publishers
impressionsReceived Impressions Advertisers
installRateDelivered Install rate Publishers
installRateReceived Install rate Advertisers
installsDelivered Installs Publishers
installsReceived Installs Advertisers
moneyEarned Money earned Publishers
moneySpent Money spent Advertisers
platform iOS, Google Play, or Amazon Everyone
videoCompletedDelivered Completed video views Publishers
videoCompletedReceived Completed video views Advertisers
  ▲ Back to top
You might also like…

Last Updated on December 16, 2020