Analytics Methods

Campaign analytics

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 methodGET
Endpointhttps://analytics.chartboost.com/v3/metrics/campaign
Example Requesthttps://analytics.chartboost.com/v3/metrics/campaign?dateMin={{Minimum date}}&dateMax={{Maximum date}}&userId={{Chartboost customer’s user ID}}&userSignature={{CB customer’s user signature}}

Parameter

ParameterRequest TypeRequired?DescriptionDefault
aggregateStringOptionalAggregate the results over time (daily, weekly, monthly)Daily
campaignIdStringOptionalCampaign ID (can be either To Campaign ID or From Campaign ID based on groupBy and role)N/A
campaignTypeStringOptionalnetwork,cross_promonetwork
dateMinStringRequiredThe minimum date (YYYY-MM-DD)N/A
dateMaxStringRequiredThe maximum date (YYYY-MM-DD)N/A
groupByStringOptionalOne of the following: 'country' 'app' 'app creative' 'target creative''date''campaign''campaign_target''campaign_type'None
platformStringOptionalFilter by specific platforms (iOS, Google Play, Amazon)All
roleStringOptionaladvertiserBoth

Response Fields

ParameterDescriptionReturned for…
adTypeId1 = interstitial 2 = more_apps 3 = in_play 4 = rewarded_video 5 = video_interstitial 10 = bannerEveryone
appApp nameEveryone
campaignCampaign nameEveryone
campaignIdCampaign ID (can be either To Campaign ID or From Campaign ID based on groupBy and role)Everyone
campaignTargetCampaign target name (only returned when grouping by campaign_targetAdvertisers
campaignSubTypeuser_acquisitionEveryone
clicksDeliveredClicks deliveredPublishers
clicksReceivedClicks receivedAdvertisers
cpcvEarnedRatio of money earned from completed video views to completed video viewsAdvertisers
cpcvSpentRatio of money spent on completed video views to number of completed video viewsPublishers
creativeAdvertised creative name (only returned when grouping by creative)Advertisers
ctrDeliveredClickthrough rate for delivered impressionsPublishers
ctrReceivedClickthrough rate for received impressionsAdvertisers
dtDate (YYYY-MM-DD)Everyone
ecpmEarnedEarnings per 1,000 impressionsPublishers
ecpmSpentCost per 1,000 impressionsAdvertisers
impressionsDeliveredImpressions delivered by the publisherPublishers
impressionsReceivedImpressions received by the advertiserAdvertisers
installDeliveredInstalls deliveredPublishers
installRateDeliveredInstall ratePublishers
installRateReceivedInstall rateAdvertisers
InstallReceivedInstallsAdvertisers
moneyEarnedMoney earnedPublishers
moneySpentMoney spentAdvertisers
videoCompletedDeliveredCompleted video views deliveredPublishers
videoCompletedReceivedCompleted video views receivedAdvertisers

App analytics

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

HTTP methodGET
Endpointhttps://analytics.chartboost.com/v3/metrics/app
Example Requesthttps://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

ParameterRequest typeRequired?DescriptionDefault
aggregateStringOptionalAggregate the results over time (daily, weekly, monthly)Daily
appIdStringOptionalOne or more (comma-separated) app IDsAll
dateMaxStringRequiredThe maximum date (YYYY-MM-DD)N/A
dateMinStringRequiredThe minimum date (YYYY-MM-DD)N/A
groupByStringOptionalOne of the following: app ad_type, app date ad_location (Publishers only), platform campaign_typeNone
platformStringOptionalAny of the following: iOS, Google Play, AmazonAll
roleStringOptionaladvertiser or publisherBoth

Response Fields

ad_typeCreative ad type Learn more about ad types ▶Everyone, only when groupBy=ad_type,app
allInstallsNumber of total installs accrued regardless of source (Chartboost or otherwise)Everyone
appApp nameEveryone
appBundleIdNo longer sent; user will see Deprecated in reportsEveryone
appIdChartboost app IDEveryone
bootupsNumber of times a user launches your app on a deviceEveryone
campaignTypenetwork, cross_promoEveryone, only when groupBy=campaignType
clicksDeliveredClicks deliveredPublishers
clicksReceivedClicks receivedAdvertisers
cpcvEarnedRatio of money earned from completed video views to completed video viewsPublishers
cpcvSpentRatio of money spent on completed video views to number of completed video viewsAdvertisers
ctrlDeliveredClickthrough rate for delivered impressionsPublishers
ctrReceivedClickthrough rate for received impressionsAdvertisers
dtDate (YYYY-MM-DD)Everyone
ParameterDescriptionReturned for…
ecpmEarnedEarnings per 1,000 impressionsPublishers
ecpmSpentCost per 1,000 impressionsAdvertisers
eventLocationThe Chartboost named location of the ad being published in the app. Advertisers will seedefaultin the response field.Everyone
impressionsDeliveredImpressions delivered by the publisherPublishers
impressionsReceivedImpressions received by the advertiserAdvertisers
installDeliveredInstalls deliveredPublishers
installRateDeliveredInstall ratePublishers
installRateReceivedInstall rateAdvertisers
installReceivedInstallsAdvertisers
moneyEarnedMoney earnedPublishers
moneySpentMoney spentAdvertisers
platform>iOS, Google Play, or AmazonEveryone
uniquesNumber of unique devices that booted up the appEveryone
videoCompletedDeliveredCompleted video views deliveredPublishers
VideoCompletedReceivedCompleted video views receivedAdvertisers

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, as detailed in the “Before you begin” section.

HTTP methodGET
Endpointhttps://analytics.chartboost.com/v3/metrics/install
Example Requesthttps://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

ParameterRequest typeRequired?DescriptionDefault
campaignIdsStringOptionalOne or more (comma-separated) campaign IDsAll campaigns
campaignTypeStringOptionalnetwork, cross_promoAll
dateMaxStringRequiredThe maximum date (YYYY-MM-DD)N/A
dateMinStringRequiredThe minimum date (YYYY-MM-DD)N/A
platformStringOptionalAny of the following: iOS, Google Play, AmazonAll
roleStringOptionaladvertiser or publisherBoth

Response Fields

ParameterDescriptionReturned for…
Ad TypeCreative ad type Learn more about ad types ▶Everyone
Click TimestampDate & time (DD-MM-YYYY HH:MM:SS)Everyone
Cost TypeAdvertising bid type Learn more about bid types ▶Everyone
Cost ValueAdvertising bid amountEveryone
CountryTwo-letter country code of deviceEveryone
DateDate & time (DD-MM-YYYY HH:MM:SS)Everyone
From App BundlePublishing app bundle IDEveryone
From App IDPublishing app IDEveryone
From App NamePublishing app nameEveryone
From Campaign IDPublishing campaign IDPublishers
From Campaign NamePublishing campaign namePublishers
From Campaign Typenetwork, cross_promoPublishers
GAIDGoogle Advertising IDEveryone (Publisher only if Behavioral Targeting is disabled)
IFAiOS Identifier for Advertisers (if iOS 10 Limit Ad Tracking is disabled)Everyone (Publisher only if Behavioral Targeting is disabled)
MACMAC address (Deprecated)N/A
ModelDevice modelEveryone
OSDevice operating systemEveryone
To App BundleAdvertising app bundle IDEveryone
To App IDAdvertising app IDEveryone
To App NameAdvertising app nameEveryone
To Campaign IDAdvertising campaign IDAdvertisers
To Campaign NameAdvertising campaign nameAdvertisers
To Campaign TargetAdvertising campaign target IDEveryone
To Campaign Typenetwork, cross_promoAdvertisers
UUIDDevice Universal Unique Identifier (if available)Everyone (Publisher only if Behavioral Targeting is disabled)

App analytics grouped by country

In addition to the endpoints on the dashboard’s API Explorer page, there is a specially designed endpoint 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.

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

🚧

Caution

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

Parameters

ParameterRequest TypeRequired?DescriptionDefault
appIdsStringOptionalOne or more (comma-separated) app IDsAll apps
dateMinStringRequiredThe minimum date (YYYY-MM-DD)N/A
dateMaxStringRequiredThe maximum date (YYYY-MM-DD)N/A
campaignTypeStringOptionalnetwork or cross_promo or both (comma-separated)network
adTypeIdsStringOptionalOne or more (comma-separated) ad type IDs: 1 interstitial,3 in_play, 4 = rewarded_video, 5 = video_intersitial, 10 = banner1,4,5,10
roleStringOptionaladvertiser or publisherpublisher
timezoneStringOptionalutc or pstutc
adLocationStringOptionalOne 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

🚧

Caution

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

ParameterDescriptionReturned for…
adLocationThe Chartboost named location of the ad being published in the app. Advertisers will see default in the response field.Everyone
adTypeinterstitial, rewarded_video, video_interstitial, bannerEveryone
appApp nameEveryone
campaignTypenetwork, cross_promoEveryone
clicksDeliveredClicksPublishers
clicksReceivedClicksAdvertisers
CountryCodeTwo-letter country code, or “unknown”Everyone
cpcvEarnedRatio of money earned from completed video views to completed video viewsPublishers
cpcvSpentRatio of money spent on completed video views to number of completed video viewsAdvertisers
ctrDeliveredClick-through ratePublishers
ctrReceivedClick-through rateAdvertisers
dtDate (YYYY-MM-DD)Everyone
ecpmEarnedEarnings per 1000 impressionsPublishers
ecpmSpentCost per 1000 impressionsAdvertisers
impressionsDeliveredImpressionsPublishers
impressionsReceivedImpressionsAdvertisers
installRateDeliveredInstall ratePublishers
InstallRateReceivedInstall rateAdvertisers
installsDeliveredInstallsPublishers
installsReceivedInstallsAdvertisers
moneyEarnedMoney earnedPublishers
moneySpentMoney spentAdvertisers
platformiOS, Google Play, or AmazonEveryone
videoCompletedDeliveredCompleted video viewsPublishers
videoCompletedReceivedCompleted video viewsAdvertisers