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

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

Supported Metrics by Ad Unit

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

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

Supported Metrics by Ad Unit

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

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"
      }
   ]
}

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

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":[  
            . . .
         ]
      }
   ]
}

¹ 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

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": [ 
            . . .
         ]
      }
]

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