Monetization Reporting API
In this article you’ll learn how to use the ironSource Reporting API in order to retrieve statistics about your monetization activity.
Get Your Authentication
First, you’ll need to add an authorization header for authentication.
Authentication is based on Basic HTTP Authentication with HTTPS. The HTTP Authorization header is created based on the base64 version of username:secret key.
- username is the login/email that is used to login to our system.
- The secret key parameter is unique for your ironSource account. To retrieve it, click on your user profile on the top right corner of the screen, and select ‘My Account’. You will find the secret key in the Reporting API section:
- PHP code example for generating username:secret key:
<?php $crl = curl_init(); $base64encoded = base64_encode("[username]:[secret key]"); $header = array(); $header[] = 'Authorization: Basic '. $base64encoded; $URL='https://platform.ironsrc.com/partners/publisher/applications/<API Method>'; curl_setopt($crl, CURLOPT_URL, $URL); curl_setopt($crl, CURLOPT_HTTPHEADER, $header); $response = curl_exec($crl); curl_close($crl); ?>
General Reporting API (V4)
Description
Receive all the reporting data from the monetization ad units you serve with ironSource, including multiple metrics such as revenue, impressions and activeUsers, etc. across several breakdowns and optional filters.
Method
GET platform.ironsrc.com/partners/publisher/mediation/applications/v4/stats
Parameters
Name | Type | Description | Default | Mandatory |
startDate | String | YYYY-MM-DD (UTC Timezone) | – | Yes |
endDate | String | YYYY-MM-DD (UTC Timezone) | – | Yes |
appKey | String | Application Key (as seen on our platform). | All App keys | No |
country | String | 2 letter country code, as per ISO 3166-1 Alpha-2. | All Countries | No |
adUnits | String | Options are ‘rewardedVideo’, ‘offerWall’, ‘interstitial’ or ‘banner’. | All Ad Units | No |
metrics | String | Metrics differ based on ad unit, see table below. | All Metrics | No |
breakdowns | String | Options are ‘date’, ‘app’, ‘country’, ‘adSource’, ‘adUnits’, ‘placement’, ‘segment’, ‘instance’, ‘instanceId’, ‘platform’. | adUnits, date | No |
Supported Metrics by Ad Unit
Metric | RewardedVideo | Interstitial | Offerwall | Definition |
revenue | ✔ | ✔ | ✔ | Total amount of revenue generated |
eCPM | ✔ | ✔ | ✔ | Effective cost per thousand impressions. eCPM is average revenue you receive for every thousand ad impressions. eCPM is calculated as (Total Earnings / Impressions) x 1000. |
appFillRate | ✔ | ✔ | The number of times an ad was shown to users compared to the number of times an was requested from a specific ad source. The fillrate for each ad source is calculated as Impressions / Mediation Requests. If you choose to break down by ad source, this metric will not return in the response. | |
appRequests | ✔ | ✔ | Number of times your app requested an ad from the mediation layer. The amount of requests may differ based on filtering. If you choose to break down by ad source, this metric will not return in the response. | |
impressions | ✔ | ✔ | ✔ | An ad impression is recorded whenever an ad is displayed in your app. |
completions | ✔ | ✔ | For Rewarded Video: the amount of video completions. For Offerwall: the amount of completed offers. |
|
revenuePerCompletion | ✔ | ✔ | The ratio of revenue generated in cents per completion, calculated as revenue / completions. | |
appFills | ✔ | ✔ | The number of ad requests that generated a positive response. If you choose to break down by ad source, this metric will not return in the response. | |
useRate | ✔ | The ratio between impressions and fulfillments, calculated as impression events / total fulfillments | ||
activeUsers | ✔ | ✔ | Indicates the amount of daily active users (DAU); i.e. the average number of unique users who initiated an app session during a defined timeframe | |
engagedUsers | ✔ | ✔ | The average of active users who engaged with an ad in your app; data is drawn from impression events | |
engagedUsersRate | ✔ | ✔ | The ratio between engaged users and active users; calculated as engaged users / total active users | |
impressionsPerEngagedUser | ✔ | ✔ | Portrays how many impressions were seen by engaged users; calculated as total impression events / total engaged users | |
revenuePerActiveUser | ✔ | ✔ | Indicates the average revenue per active user (ARPU) in cents; calculated as total revenue/ total active users | |
revenuePerEngagedUser | ✔ | ✔ | Indicates the revenue earned per engaged user in cents; calculated as total revenue / total engaged users | |
clicks | ✔ | ✔ | The total number of times users clicked on ads served on your app | |
clickThroughRate | ✔ | ✔ | The ratio between impressions and clicks; calculated as clicks / impressions | |
completionRate | ✔ | Indicates the amount of users to complete a defined action | ||
adSourceChecks | ✔ | ✔ | The amount of times an ad source is asked whether it is ready to show an ad |
|
adSourceResponse | ✔ | ✔ | The number of times an ad source had an ad available to show at the time of the request | |
adSourceAvailabilityRate | ✔ | ✔ | The rate at which an ad source had an ad available when an ad was requested, calculated Impressions/ Ad Source Requests | |
sessions | ✔ | ✔ | The sum of single periods of user interaction with your app (each SDK init generates a new session) | |
engagedSessions | ✔ | ✔ | The sum of sessions in which a user interacts with an ad | |
impressionsPerSession | ✔ | ✔ | The average amount of ads served throughout a single session, calculated as Impressions/Session | |
impressionsPerEngagedSessions | ✔ | ✔ | The average amount of ad impressions during an engaged session, calculated as Impressions/Engaged Sessions | |
sessionsPerActiveUser | ✔ | ✔ | The average number of sessions generated by an active user on a daily basis, calculated as Sessions/Active User |
Request Example URL
platform.ironsrc.com/partners/publisher/mediation/applications/v3/stats?startDate=2016-08-01&endDate=2016-08-04&appId=1234321&adUnits=rewardedVideo
JSON response
[ { "date": "2017-01-08", "adUnits": "Rewarded Video", "data": [ { "revenue": 167.56, "eCPM": 17.2, "mediationFillRate": 92.8, "mediationRequests": 13989, "mediationFills": 12982, "impressions": 9742, "videoCompletions": 9203, "averageRevenue": 1.82, "useRate": 75.04, "activeUsers": 6451, "engagedUsers": 2568, "engagementRate": 39.81, "impressionsPerEngagedUser": 3.79, "revenuePerActiveUser": 2.6, "revenuePerEngagedUser": 6.52, "sessions": 14598, "engagedSessions": 4157, "impressionPerEngagedSessions": 2.34, "impressionsPerSession": 0.67, "sessionsPerActiveUser": 2.26, "adSourceChecks": 33899, "adSourceResponses": 25663, "availabilityRate": 75.7 } ] }, { "date": "2017-01-09", "adUnits": "Rewarded Video", "data": [ { "revenue": 93.83, "eCPM": 17.04, "mediationFillRate": 89.05, "mediationRequests": 8646, "mediationFills": 7699, "impressions": 5505, "videoCompletions": 5208, "averageRevenue": 1.8, "useRate": 71.5, "activeUsers": 4142, "engagedUsers": 1503, "engagementRate": 36.29, "impressionsPerEngagedUser": 3.66, "revenuePerActiveUser": 2.27, "revenuePerEngagedUser": 6.24, "sessions": 9582, "engagedSessions": 2512, "impressionPerEngagedSessions": 2.19, "impressionsPerSession": 0.57, "sessionsPerActiveUser": 2.31, "adSourceChecks": 19425, "adSourceResponses": 14225, "availabilityRate": 73.23 } ]
Appendices
General Reporting API (V3)
Description
Receive all the reporting data from the monetization ad units you serve with ironSource, including multiple metrics such as revenue, impressions and activeUsers, etc. across several breakdowns and optional filters.
Method
GET platform.ironsrc.com/partners/publisher/mediation/applications/v3/stats
Parameters
Name | Type | Description | Default | Mandatory |
startDate | String | YYYY-MM-DD (UTC Timezone) | – | Yes |
endDate | String | YYYY-MM-DD (UTC Timezone) | – | Yes |
appId | String | Application Key (as seen on our platform). | All App IDs | No |
country | String | 2 letter country code, as per ISO 3166-1 Alpha-2. | All Countries | No |
adUnits | String | Options are ‘rewardedVideo’, ‘offerWall’ or ‘interstitial’. | All Ad Units | No |
metrics | String | Metrics differ based on ad unit, see table below. | All Metrics | No |
breakdowns | String | Options are ‘date’, ‘app’, ‘country’, ‘adSource’, ‘adUnits’, ‘placement’. | adUnits, date | No |
Supported Metrics by Ad Unit
Metric | RewardedVideo | Interstitial | Offerwall | Definition |
revenue | ✔ | ✔ | ✔ | Total amount of revenue generated |
eCPM | ✔ | ✔ | ✔ | Effective cost per thousand impressions. eCPM is average revenue you receive for every thousand ad impressions. eCPM is calculated as (Total Earnings / Impressions) x 1000. |
mediationFillRate | ✔ | ✔ | The number of times an ad was shown to users compared to the number of times an was requested from a specific ad source. The fillrate for each ad source is calculated as Impressions / Mediation Requests. If you choose to break down by ad source, this metric will not return in the response. | |
mediationRequests | ✔ | ✔ | Number of times your app requested an ad from the mediation layer. The amount of requests may differ based on filtering. If you choose to break down by ad source, this metric will not return in the response. | |
impressions | ✔ | ✔ | ✔ | An ad impression is recorded whenever an ad is displayed in your app. |
completions | ✔ | ✔ | For Rewarded Video: the amount of video completions. For Offerwall: the amount of completed offers. |
|
averageRevenue | ✔ | ✔ | The ratio of revenue generated in cents per completion, calculated as revenue / completions. | |
mediationFills | ✔ | ✔ | The number of ad requests that generated a positive response. If you choose to break down by ad source, this metric will not return in the response. | |
useRate | ✔ | The ratio between impressions and fulfillments, calculated as impression events / total fulfillments | ||
activeUsers | ✔ | ✔ | Indicates the amount of daily active users (DAU); i.e. the average number of unique users who initiated an app session during a defined timeframe | |
engagedUsers | ✔ | ✔ | The average of active users who engaged with an ad in your app; data is drawn from impression events | |
engagedUsersRate | ✔ | ✔ | The ratio between engaged users and active users; calculated as engaged users / total active users | |
impressionsPerEngagedUser | ✔ | ✔ | Portrays how many impressions were seen by engaged users; calculated as total impression events / total engaged users | |
revenuePerActiveUser | ✔ | ✔ | Indicates the average revenue per active user (ARPU) in cents; calculated as total revenue/ total active users | |
revenuePerEngagedUser | ✔ | ✔ | Indicates the revenue earned per engaged user in cents; calculated as total revenue / total engaged users | |
clicks | ✔ | ✔ | The total number of times users clicked on ads served on your app | |
clickThroughRate | ✔ | ✔ | The ratio between impressions and clicks; calculated as clicks / impressions | |
completionRate | ✔ | Indicates the amount of users to complete a defined action | ||
adSourceChecks | ✔ | ✔ | The amount of times an ad source is asked whether it is ready to show an ad |
|
adSourceResponse | ✔ | ✔ | The number of times an ad source had an ad available to show at the time of the request | |
availabilityRate | ✔ | ✔ | The rate at which an ad source had an ad available when an ad was requested, calculated Impressions/ Ad Source Requests | |
sessions | ✔ | ✔ | The sum of single periods of user interaction with your app (each SDK init generates a new session) | |
engagedSessions | ✔ | ✔ | The sum of sessions in which a user interacts with an ad | |
impressionsPerSession | ✔ | ✔ | The average amount of ads served throughout a single session, calculated as Impressions/Session | |
impressionsPerEngagedSessions | ✔ | ✔ | The average amount of ad impressions during an engaged session, calculated as Impressions/Engaged Sessions | |
sessionsPerActiveUser | ✔ | ✔ | The average number of sessions generated by an active user on a daily basis, calculated as Sessions/Active User |
General Reporting API (V2)
Description
Receive all the reporting data from the monetization ad units you serve with ironSource, including multiple metrics such as revenue, impressions and activeUsers, etc. across several breakdowns and optional filters.
Method
GET platform.ironsrc.com/partners/publisher/mediation/applications/v2/stats
Parameters
Name | Type | Description | Default | Mandatory |
startDate | String | YYYY-MM-DD (UTC Timezone) | – | Yes |
endDate | String | YYYY-MM-DD (UTC Timezone) | – | Yes |
appId | String | Application Key (as seen on our platform). | All App IDs | No |
country | String | 2 letter country code, as per ISO 3166-1 Alpha-2. | All Countries | No |
adUnits | String | Options are ‘rewardedVideo’, ‘offerWall’ or ‘interstitial’. | All Ad Units | No |
metrics | String | Metrics differ based on ad unit, see table below. | All Metrics | No |
breakdowns | String | Options are ‘date’, ‘app’, ‘country’, ‘adSource’, ‘adUnits’, ‘placement’. | adUnits, date | No |
Metric | RewardedVideo | Interstitial | Offerwall | Definition |
revenue | ✔ | ✔ | ✔ | Total amount of revenue generated |
eCPM | ✔ | ✔ | ✔ | Effective cost per thousand impressions. eCPM is average revenue you receive for every thousand ad impressions. eCPM is calculated as (Total Earnings / Impressions) x 1000. |
fillRate | ✔ | ✔ | The number of times an ad was shown to users compared to the number of times an ad was requested from the mediation layer. The fillrate for each ad source is calculated as Impressions / Mediation Requests. | |
requests | ✔ | ✔ | Number of times your app requested an ad from the mediation layer. The amount of requests may differ based on filtering. | |
impressions | ✔ | ✔ | ✔ | An ad impression is recorded whenever an ad is displayed in your app. |
completions | ✔ | ✔ | For Rewarded Video: the amount of video completions. For Offerwall: the amount of completed offers. |
|
averageRevenue | ✔ | ✔ | The ratio of revenue generated in cents per completion, calculated as revenue / completions. | |
fulfillments | ✔ | ✔ | The number of ad requests that generated a positive response. | |
impressionPerFulfillmentRate | ✔ | The ratio between impressions and fulfillments, calculated as impression events / total fulfillments | ||
activeUsers | ✔ | ✔ | Indicates the amount of daily active users (DAU); i.e. the average number of unique users who initiated an app session during a defined timeframe | |
engagedUsers | ✔ | ✔ | The average of active users who engaged with an ad in your app; data is drawn from impression events | |
engagedUsersRate | ✔ | ✔ | The ratio between engaged users and active users; calculated as engaged users / total active users | |
impressionsPerEngagedUser | ✔ | ✔ | Portrays how many impressions were seen by engaged users; calculated as total impression events / total engaged users | |
revenuePerActiveUser | ✔ | ✔ | Indicates the average revenue per active user (ARPU) in cents; calculated as total revenue/ total active users | |
revenuePerEngagedUser | ✔ | ✔ | Indicates the revenue earned per engaged user in cents; calculated as total revenue / total engaged users | |
clicks | ✔ | ✔ | The total number of times users clicked on ads served on your app | |
clickRate | ✔ | ✔ | The ratio between impressions and clicks; calculated as clicks / impressions | |
completionRate | ✔ | Indicates the amount of users to complete a defined action |
Request Example URL
platform.ironsrc.com/partners/publisher/mediation/applications/v2/stats?startDate=2016-08-01&endDate=2016-08-04&appId=1234321&adUnits=rewardedVideo
JSON response
[ { "date": "2017-01-07", "adUnits": "Rewarded Video", "data": [ { "revenue": 212.78, "eCPM": "6.47", "fillRate": "88.56", "requests": 49408, "fulfillments": 43757, "impressions": 32898, "completions": 30947, "averageRevenue": "0.69", "impressionPerFulfillmentRate": "75.18", "activeUsers": 27224, "engagedUsers": 9182, "engagedUsersRate": 33.73, "impressionsPerEngagedUser": 3.58, "revenuePerActiveUser": 0.78, "revenuePerEngagedUser": 2.32 } ] }, { "date": "2017-01-08", "adUnits": "Rewarded Video", "data": [ { "revenue": 249.17, "eCPM": "7.12", "fillRate": "88.66", "requests": 51728, "fulfillments": 45864, "impressions": 34979, "completions": 32961, "averageRevenue": "0.76", "impressionPerFulfillmentRate": "76.27", "activeUsers": 27080, "engagedUsers": 9420, "engagedUsersRate": 34.79, "impressionsPerEngagedUser": 3.71, "revenuePerActiveUser": 0.92, "revenuePerEngagedUser": 2.65 } ] }
API for Apps List
Description
Get a list of applications that are using monetization Ad Units. The list you will get in the response will include all your apps.
Method
GET /publisher/applications
Parameters
None
Response
GET https://platform.ironsrc.com/partners/publisher/applications
JSON response
{ "status": "full", "data": [ { "app_id": "1234", "application_name": "Super App", "platform": "apple_itunes", "bundle_id": "com.Super.SuperApp" }, { "app_id": "5678", "application_name": "Awesome App", "platform": "google_play" } ] }
Name | Type | Description |
status | full / partial | “full” means that the information collected for the date interval is complete, i.e. if we scrape at a later date this information will be the same. “partial” could be used to indicate that the your network has not finished aggregating the data. |
app_id | String | Your app ID |
application_name | String | The application name |
platform | Enum | Would contain: apple_itunes / google_play |
bundle_id | String | The native app store bundle_id. This can either be the Google Play package name or the Apple App id |
Appendix C: API for App Stats in the ironSource Marketplace network (Deprecated)
Description
Get the performance statistics (e.g impressions, clicks, revenue) for ironSource Demand only, coming from each app with breakdown of geographic data (if applicable).
Method
GET /publisher/applications/stats/
Parameters
Name | Type | Description | Required |
start_date | String | YYYY-MM-DD (UTC Timezone) | Yes |
end_date | String | YYYY-MM-DD (UTC Timezone) | Yes |
app_id | String | The app ID, Multiple app_id can be set If not set, then return data for all apps |
No |
Response
GET https://platform.ironsrc.com/partners/publisher/applications/stats?start_date=2013-01-01&end_date=2013-01-02&app_id=47bf92,47bf93
JSON Response
{ "status":"partial", "data":[ { "date":"2014-01-01", "campaign_id":"12345", "data":[ { "country_code":"US", "expense":1021, "currency":"USD", "impressions":24, "clicks":20, "conversions":19 }, { "country_code":"GB", "expense":3041, "currency":"USD", "impressions":8, "clicks":6, "conversions":2, "custom_params":{ "cross_promo":1 } } ] }, { "date":"2014-01-02", "campaign_id":"5678", "data":[ . . . ] } ] }
Name | Type | Description |
status | full / partial | “full” means that the information collected for the date interval is complete, i.e. if we scrape at a later date this information will be the same. “partial” could be used to indicate that the your network has not finished aggregating the data |
date | String | YYYY-MM-DD (UTC Timezone) |
app_id | String | Your Application Key (as seen on the apps page) |
country_code | String | 2 letter country code, as per ISO 3166-1 Alpha-2 |
revenue | Int | Money in cents² |
currency | String | ISO 4217 Code, e.g. USD, GBP |
impressions | Int | Number of impressions |
clicks | Int | Number of clicks |
conversions | Int | Number of conversions |
¹ If the expense is 4 USD, the number sent will be 4 * 100 = 400. Do the same for other currencies, even if there is no subunit corresponding to the US cent. E.g., if the expense is 50 JPY, the number sent should be 50 * 100 = 5000.
API for App Stats in the ironSource Mediation network (Deprecated)
Description
Get the publisher stats (e.g. impressions, clicks, revenue) for Rewarded Video Mediation, coming from each app with breakdown of ad network and geographic data (if applicable).
Method
GET /publisher/mediation/applications/stats/
Parameters
Name | Type | Description | Required |
start_date | String | YYYY-MM-DD (UTC Timezone) | Yes |
end_date | String | YYYY-MM-DD (UTC Timezone) | Yes |
app_id | String | Our Application Key (as seen on the apps page), Multiple ‘app_id’s can be set If not set, then return data for all apps |
No |
country | String | comma separated countries, 2 letter country code, as per ISO 3166-1 Alpha-2 | No |
ad_units | String | comma separated values. Options are: ‘rewardedVideo’, ‘interstitial’; default is (“rewardedVideo”) | No |
breakdowns | String | comma separated values. Options are: ‘country’, ‘adSource’, ‘app’; default is all (“country,adSource,app”) | No |
Response
GET https://platform.ironsrc.com/partners/publisher/mediation/applications/stats?start_date=2013-01-01&end_date=2013-01-02&app_id=1234,5678
JSON response
[ { "date": "2014-01-01", "app_id": "1234", "app_name": "app1", "provider_name": "ironSource", "data": [ { "country_code": "US", "revenue": 1025, "currency": "USD", "impressions": 0, "requests": 39, "fill_rate": "0.00", "ecpm": "0.00" }, { "country_code": "GB", "revenue": 200, "currency": "USD", "impressions": 10, "requests": 20, "fill_rate": "0.00", "ecpm": "0.00" } ] }, { "date": "2014-01-02", "app_id": "5678", "app_name": "app2", "provider_name": "ironSource", "data": [ . . . ] } ]
Name | Type | Description |
date | String | YYYY-MM-DD (UTC Timezone) |
app_id | String | Your Application Key (as seen on the apps page) |
country_code | String | 2 letter country code, as per ISO 3166-1 Alpha-2 |
revenue | Int | Money in cents¹ |
currency | String | ISO 4217 Code, e.g. USD, GBP |
impressions | Int | Number of impressions |
requests | Int | Number of requests |
fill_rate | String | Fill rate in percentage |
ecpm | String | eCPM in cents |
¹ If the expense is 4 USD, the number sent will be 4 * 100 = 400. Do the same for other currencies, even if there is no subunit corresponding to the US cent. E.g., if the expense is 50 JPY, the number sent should be 50 * 100 = 5000.