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:
    ironsource-platform-monetization-reporting-api-secret-key
  • 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

Note: all our parameters support multiple comma separated values.

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

Note: all our parameters support multiple comma separated values.

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

Note: all our parameters support multiple comma separated values.
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.
 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.