The InMobi Publisher Reporting API 3.0 lets you automate downloading performance data for your apps. This topic walks you through key API features and use cases.
The publisher reporting API conforms to REST specifications and supports JSON format. To query reporting API, you need to send the API Key in secretKey.
Our API endpoint for all publishers (except those originating from China) is https://api.inmobi.com/v3.0/reporting/publisher with headers "Content-Type:application/json" and "Accept:application/json".
An API Key can only be generated by the Publisher Admin of the account for him or other users. Other user roles will not be able to generate an API Key for themselves or others. Also, only Pub Admin users can reset the keys for other users within the account, other users can only reset their own API key.
Two actions that can be performed on the API Key sub-tab under the Account Settings section:
If you forget the previously generated API Key, you can reset it by hovering over their email ID on the API Key sub-tab.
The Publisher Admin can reset the API Key for themselves and others, while other User Roles can only reset the API Key for themselves.
A valid session is required to authenticate any API request. A session is valid for 8 hours from the time of issue. An API key can be used to generate up to 15 valid sessions in 8 hours timeframe.
Sample Request
Support Center
curl -v <a href="https://api.inmobi.com/v1.0/generatesession/generate"> https://api.inmobi.com/v1.0/generatesession/gener...</a>
-H "userName:#######"
-H "secretKey:########"
The password is not mandatory for generating a valid session, but if you’ve been using it in your request, you will not be affected.
Sample Response
JSON
{
"respList": [{
"sessionId": "b8************************d31942",
"accountId": "4028cb************************14",
"subAccounts": null
}],
"error": false,
"errorList": []
}
The session can be more than 1000 characters long. It is recommended for you to take the appropriate data type.
All data is returned in the GMT time zone. For example, this is the API call to get the impression count:
Sample Request
curl -v -X POST
-H "Content-Type:application/json"
-H "Accept:application/json"
-H "accountId:14a************************9e"
-H "secretKey: ####"
-H "sessionId: ###"
-d '{"reportRequest":{"metrics":["adImpressions"],"timeFrame":"2017-07-20:2017-07-30","groupBy":["date"], "filterBy":[{ "filterName":"adImpressions", "filterValue": "300" , "comparator":">"}]}}'
<a href="https://api.inmobi.com/v3.0/reporting/publisher">
https://api.inmobi.com/v3.0/reporting/publisher
</a>
Sample Response
{
"error": false,
"respList": [{
"adImpressions": 1786296,
"date": "2017-07-24 00:00:00"
}, {
"adImpressions": 1951438,
"date": "2017-07-25 00:00:00"
}, {
"adImpressions": 8062637,
"date": "2017-07-29 00:00:00"
}, {
"adImpressions": 11151057,
"date": "2017-07-30 00:00:00"
}, {
"adImpressions": 4190525,
"date": "2017-07-21 00:00:00"
}, {
"adImpressions": 10044183,
"date": "2017-07-27 00:00:00"
}, {
"adImpressions": 3881191,
"date": "2017-07-22 00:00:00"
}, {
"adImpressions": 9841295,
"date": "2017-07-20 00:00:00"
}, {
"adImpressions": 4605890,
"date": "2017-07-26 00:00:00"
}, {
"adImpressions": 6175605,
"date": "2017-07-28 00:00:00"
}, {
"adImpressions": 2247567,
"date": "2017-07-23 00:00:00"
}]
}
The InMobi Reporting API supports CSV outputs where publishers can retrieve inventory performance data.
The inventory performance data only contains information about apps and ad units. This report includes ad requests, rendered impressions, clicks, and CTR metrics. Customers can calculate inventory fill rate based on request data.
Below are the metrics, grouping, and filtering parameters that are supported.
Metrics
| Parameter | Description |
| adRequests | Aggregate of all ad requests |
| adImpressions | Aggregate of all impressions rendered |
| clicks | Aggregate of all clicks recorded |
| earnings | The average earnings |
| servedImpressions | Aggregate of all served impressions. |
| costPerMille | eCPM value (cost per thousand impressions) |
| fillRate | The fill rate value |
Grouping
| Parameter | Description |
| country | Group the reports by region |
| requestSlot | Group the reports by the placement size (for instance 480x320) |
| platform | Group the reports by operating system |
| date | Date when the report is aggregated |
| account | Group the reports by accounts (sub-accounts within the publisher’s account) |
| inmobiAppId | Group the reports by App ID (all placements for an app) |
| placement | placement |
| adUnitType | Group the reports by ad unit type |
| integrationDirect | Group reports generated by integration type |
Filtering
| Parameter | Value Type | Description | Comparator |
| country | String | Filter by target country, e.,g, “South Korea” | = |
| inmobiAppId | Long | Unique identifier for the app, eg., 14999472554## Filter by app id | =, IN |
| inmobiAppName | Name | Filter by app name, e.g. “Horoscoper” | = |
| placementId | Long | Unique identifier for a placement under the app e.g, 1478496451110. Filter by placement Id. | = |
| placementName | String | Filter by placement name,e.g, “Default Interstitial Placement” | = |
| platform | String | Filter by operating system e.g., IOS, ANDROID | =, IN |
| earnings | Long | Filter by total earnings, e.g, 100 |
>, <, =, >=, <= |
| adImpressions | Long | Filter by impressions rendered E.g., 100 |
>, <, =, >=, <= |
| adUnitType | String | Filter by ad unit type | =, IN |
Pagination
Pagination is required if the resulting dataset on a request is potentially more than 5000 rows of data. We have restricted the number of data rows to 5000 on every reporting API call. Pagination can be achieved on request with the following parameters:
To get the complete set of data, offset value of subsequent call should be the sum of (offset + length) on previous call. Last such call should get rows less than or equal to “length”.
"orderBy" and "orderType" must be sent in the request whenever pagination is used, to avoid duplicate records appearing in the response.
For instance: Fetching three records
Request
curl -v -X POST
-H "Content-Type:application/json"
-H "Accept:application/json"
-H "accountId:4028cb************************14"
-H "secretKey: ####"
-H "sessionId: ####”
-d '{"reportRequest":{"metrics":["clicks"],"timeFrame":"2017-07-20:2017-07-30","groupBy":["country"],"offset": 0, "length": 3, "orderBy": ["clicks"], "orderType": "desc"}}'
<a href="https://api.inmobi.com/v3.0/reporting/publisher">
https://api.inmobi.com/v3.0/reporting/publisher
</a>
Response
{
"error": false,
"respList": [
{
"clicks": 8,
"country": "Finland",
"countryId": 105
},
{
"clicks": 4,
"country": "Suriname",
"countryId": 290
},
{
"clicks": 3,
"country": "Belarus",
"countryId": 142
}
]
}
Building on the above example, to retrieve 13000 records, there needs to be 3 reporting calls with the following values of offset and length:
1st call : offset = 0, length = 5000
2nd call : offset = 5000, length = 5000
3rd call : offset = 10000, length = 3000
Let’s look at some examples of requests and responses with various scenarios of data.
Sample 1: Clicks and earnings for the account
Request
curl -v -X POST
-H "Content-Type:application/json"
-H "Accept:application/json"
-H "accountId:14a************************9e"
-H "secretKey: ####"
-H "sessionId: ####”
-d '{"reportRequest":{"metrics":["earnings","clicks"],"timeFrame":"2017-07-20:2017-07-30"}}'
<a href="https://api.inmobi.com/v3.0/reporting/publisher">
https://api.inmobi.com/v3.0/reporting/publisher
</a>
Response
{
"error": false,
"respList": [{
"clicks": 3901721,
"earnings": 2076.485
}]
}
Sample 2: Clicks and earnings for the account group by Date
Request
curl -v -X POST
-H "Content-Type:application/json"
-H "Accept:application/json"
-H "accountId:4028cb************************14
-H "secretKey: ####"
-H "sessionId: ####”
-d '{"reportRequest":{"metrics":["earnings","clicks"],"groupBy":["date"],"timeFrame":"2017-07-20:2017-07-30"}}'
<a href="https://api.inmobi.com/v3.0/reporting/publisher">
https://api.inmobi.com/v3.0/reporting/publisher
</a>
Response
{
"error": false,
"respList": [{
"clicks": 131833,
"date": "2017-07-24 00:00:00",
"earnings": 228.166
}, {
"clicks": 145627,
"date": "2017-07-25 00:00:00",
"earnings": 231.309
}, {
"clicks": 351536,
"date": "2017-07-29 00:00:00",
"earnings": 85.275
}, {
"clicks": 563490,
"date": "2017-07-30 00:00:00",
"earnings": 148.264
}, {
"clicks": 318369,
"date": "2017-07-21 00:00:00",
"earnings": 313.458
}, {
"clicks": 773215,
"date": "2017-07-27 00:00:00",
"earnings": 76.041
}, {
"clicks": 295016,
"date": "2017-07-22 00:00:00",
"earnings": 276.296
}, {
"clicks": 471678,
"date": "2017-07-20 00:00:00",
"earnings": 314.018
}, {
"clicks": 350179,
"date": "2017-07-26 00:00:00",
"earnings": 116.173
}, {
"clicks": 332405,
"date": "2017-07-28 00:00:00",
"earnings": 69.499
}, {
"clicks": 168373,
"date": "2017-07-23 00:00:00",
"earnings": 217.987
}]
}
Sample 3: Ad Requests for a specific app ID
Request
curl -v -X POST
-H "Content-Type:application/json"
-H "Accept:application/json"
-H "accountId:4028cb************************14
-H "secretKey: ####"
-H "sessionId: ####”
-d '{"reportRequest":{"metrics":["adRequests"],"timeFrame":"2017-07-20:2017-07-30","filterBy":[{ "filterName":"inmobiAppId", "filterValue": "1489455016170" , "comparator":"="}]}}'
<a href="https://api.inmobi.com/v3.0/reporting/publisher">
https://api.inmobi.com/v3.0/reporting/publisher
</a>
Response
{
"error": false,
"respList": [{
"adRequests": 179623
}]
}
Here is a list of possible error codes in the table below:
| Error Codes | Description |
| 1000 | Unexpected error in the publisher report. |
| 1001 | The request object is invalid. |
| 1002 | The request contains an invalid offset. |
| 1003 | The request contains an invalid length. |
| 1004 | Invalid client request. Please make sure the client request is properly formed. |
| 2000 | Account ID is missing in the request. Please pass the account ID in the request. |
| 2001 | One or more of the account IDs passed by in filter is either invalid, or you are not authorized to access their data : [List of invalid account IDs]. |
| 2021 | The request contains invalid metrics: [List of invalid metrics]. |
| 2022 | The request contains an invalid group by: [List of invalid groupBys]. |
| 2023 | The request contains an invalid filter by: [List of invalid filters]. |
| 2024 | The filters on [List of invalid filters] contain invalid comparators. Comparators should have one of the values: [List of valid filters]. |
| 2025 | The request contains an invalid filter by values for the filter by country: [List of invalid countries]. |
| 2027 | The from-date cannot be after the to-date. |
| 2028 | The date passed in the request start date and/or end date has an invalid format. |
| 2029 | The request contains invalid order by(s) on: [List of invalid orderBys]. The result can only be ordered on the fields sent in metrics or group by. |
| 2030 | The order type in the request is invalid. Valid values are 'asc' and 'desc'. |
| 2031 | The request contains the following filters which have no filter values: [List of invalid filters]. Please provide filter values. |
| 2032 | The time frame sent in the request is in an invalid format. The expected format is start date:end date( yyyy-MM-dd:yyyy-MM-dd). |
| 2033 | The request contains invalid filter by values for the filter by manufacturer: [List of invalid manufacturers]. |
| 2034 | The request contains invalid filter by values for the filter by platform: [List of invalid platforms]. |
| 2036 | The from-date or to-date cannot be after today. |
The earnings are reported in US dollars.
There is no limit on the number of requests per session.
You can fetch a maximum of 15 sessions in a day.
Once the issue is detected, the usual ETA is 24-48 hours.
The usual data delay is 4-5 hours. Also, InMobi follows the GMT.
6 months.
| Metric | Definition | Calculation |
| eCPM | Effective CPM: Effective cost per Mille |
Total earnings / (Total impressions *1000) |
| CTR |
Click through rates is # of clicks your ad receives divided by # of times your ad is shown |
Total # of clicks / (Total # of ad impressions) |
| Total ad requests | Total # of ad requests received from publishers | # of ad requests |
| Ad impressions served | Ad impressions served by InMobi | # of ad impressions served |
| Ad impressions rendered | Ad impressions successfully viewed by the user | # of ads rendered |
| Fill Rate | The percentage of ad served from ads requested | % of successful impressions / (Total # of requests) |
| Ad render rate | The percentage of served ads rendered |
# of ads rendered / (# of ad impressions served) |
| Publisher Revenue | Total revenue to publisher |
By installing this SDK update, you agree that your Children Privacy Compliance setting remains accurate or that you will update that setting, whenever there is a change in your app's audience. You may update the app's Children Privacy Compliance settings at https://publisher.inmobi.com/my-inventory/app-and-placements.