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.

 NoteOur Reporting API is limited to 20 requests every 10 minutes.

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/mediation/applications/<latest version>/stats;
     curl_setopt($crl, CURLOPT_URL, $URL);
    curl_setopt($crl, CURLOPT_HTTPHEADER, $header);
     $response = curl_exec($crl);
     curl_close($crl);
     ?>

General Reporting API (V5)

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/v5/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
adSource String Mediated ad networks, Including ironSource All Ad Sources No
metrics String Metrics differ based on ad unit, see table below. All Metrics No
breakdowns String For available breakdowns – See Note below adUnits, date No

Note: Available breakdowns are: ‘date’, ‘app’, ‘country’, ‘adSource’, ‘adUnits’, ‘placement’, ‘segment’, ‘instance’, ‘platform’.

Supported Metrics by Ad Unit

 

Metric RewardedVideo Interstitial Offerwall Banner
revenue
eCPM
appFillRate
appRequests
impressions
completions
revenuePerCompletion
appFills
useRate
activeUsers
engagedUsers
engagedUsersRate
impressionsPerEngagedUser
revenuePerActiveUser
revenuePerEngagedUser
clicks
clickThroughRate
completionRate
adSourceChecks
adSourceResponse
adSourceAvailabilityRate
sessions
engagedSessions
impressionsPerSession
impressionsPerEngagedSessions
sessionsPerActiveUser

Note: all our parameters support multiple comma separated values.

Metrics 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.
  • appFillRateThe number of times an ad was shown to users compared to the number of times an was requested from a specific ad source. The fill-rate 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
  • sessionsThe 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/v5/stats?startDate=2018-08-01&endDate=2018-08-02&app=6facfc75&adSource=AdMob&adUnits=rewardedVideo

JSON response

[
 {
 "date": "2018-08-01",
 "adUnits": "Rewarded Video",
 "data": [
 {
 "revenue": 3946.64,
 "eCPM": 3.3,
 "appFillRate": 96.74,
 "appRequests": 27754194,
 "appFills": 26849523,
 "impressions": 1196550,
 "videoCompletions": 939447,
 "revenuePerCompletion": 0.42,
 "useRate": 4.46,
 "activeUsers": 7615553,
 "engagedUsers": 368545,
 "engagementRate": 4.84,
 "impressionsPerEngagedUser": 3.25,
 "revenuePerActiveUser": 0.05,
 "revenuePerEngagedUser": 1.07,
 "sessions": 14563950,
 "engagedSessions": 6034635,
 "impressionPerEngagedSessions": 0.2,
 "impressionsPerSession": 0.08,
 "sessionsPerActiveUser": 1.91,
 "adSourceChecks": 5271515,
 "adSourceResponses": 1217324,
 "adSourceAvailabilityRate": 23.09,
 "clicks": 18055,
 "clickThroughRate": 1.51
 }
 ]
 },
 {
 "date": "2018-08-02",
 "adUnits": "Rewarded Video",
 "data": [
 {
 "revenue": 4265.86,
 "eCPM": 5.64,
 "appFillRate": 96.66,
 "appRequests": 27249186,
 "appFills": 26340369,
 "impressions": 755759,
 "videoCompletions": 609893,
 "revenuePerCompletion": 0.7,
 "useRate": 2.87,
 "activeUsers": 7526721,
 "engagedUsers": 255409,
 "engagementRate": 3.39,
 "impressionsPerEngagedUser": 2.96,
 "revenuePerActiveUser": 0.06,
 "revenuePerEngagedUser": 1.67,
 "sessions": 14443673,
 "engagedSessions": 6017406,
 "impressionPerEngagedSessions": 0.13,
 "impressionsPerSession": 0.05,
 "sessionsPerActiveUser": 1.92,
 "adSourceChecks": 3425750,
 "adSourceResponses": 775622,
 "adSourceAvailabilityRate": 22.64,
 "clicks": 7968,
 "clickThroughRate": 1.05
 }
 ]
 }
]

API for Apps List (V2)

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 platform.ironsrc.com/partners/publisher/applications/v2

Parameters

None

Request Example URL

GET https://platform.ironsrc.com/partners/publisher/applications/v2/stats?

JSON Response

Name Type Description
appKey String
Application Key (as seen on our platform).
application_name String
The application name
platform String IOS or Android
bundle_id String
The native app store bundle_id

Appendices

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 For available breakdowns – See Note below adUnits, date No

Supported Metrics by Ad Unit

Metric RewardedVideo Interstitial Offerwall
revenue
eCPM
mediationFillRate
mediationRequests
impressions
completions
averageRevenue
mediationFills
useRate
activeUsers
engagedUsers
engagedUsersRate
impressionsPerEngagedUser
revenuePerActiveUser
revenuePerEngagedUser
clicks
clickThroughRate
completionRate
adSourceChecks
adSourceResponse
availabilityRate
sessions
engagedSessions
impressionsPerSession
impressionsPerEngagedSessions
sessionsPerActiveUser

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
revenue
eCPM
mediationFillRate
mediationRequests
impressions
completions
averageRevenue
mediationFills
useRate
activeUsers
engagedUsers
engagedUsersRate
impressionsPerEngagedUser
revenuePerActiveUser
revenuePerEngagedUser
clicks
clickThroughRate
completionRate
adSourceChecks
adSourceResponse
availabilityRate
sessions
engagedSessions
impressionsPerSession
impressionsPerEngagedSessions
sessionsPerActiveUser

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
revenue
eCPM
fillRate
requests
impressions
completions
averageRevenue
fulfillments
impressionPerFulfillmentRate
activeUsers
engagedUsers
engagedUsersRate
impressionsPerEngagedUser
revenuePerActiveUser
revenuePerEngagedUser
clicks
clickRate
completionRate

 

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 (V1)

 

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.