Contents
Overview
The reporting API offers publishers a programmatic way to access data that is present on the dashboard. Your Reporting API Key is the same for all of your apps. Each app has a unique application_id, which you can find on its respective application page.
Host
Host: https://report.api.vungle.com/ext/pub/reports/performance
Authentication
Security is handled in the request header. Find your API key in the Reports page on the Vungle dashboard. If you don't already have an API Key, email tech-support@vungle.com to request one.
Request Headers
| Key | Value | Description |
Authorization: |
Bearer [API Key] |
API Key (note the required space between Bearer and the API Key value) |
Vungle-Version: |
1 |
API Version |
Accept: |
text/csv or application/json |
Accepted data format for results. Default is text/csv. |
Results
- Format: We support JSON and CSV outputs.
- Date range: Historical information is available for up to six months. To retrieve older data, email your account manager at tech-support@vungle.com.
- In the event of no data: Please note that if there is no data available for your query, Vungle sends back an empty 200 response. This indicates that the request has succeeded, but there is no data available to return.
Resource: GET /reports/performance
Filter Parameters
Use filter parameters to restrict the results to a subset of your performance data. Most filters are optional, in which case Vungle returns all results for that filter.
Note that the Vungle epoch is 2017-01-01, and any date prior to the epoch is considered invalid.
| Parameter name | Format | Action | If unavailable | Example |
start |
ISO8601 date | Limits the result set to performance data no earlier than this date | Rejects request | start=2017-01-01 |
end |
ISO8601 date | Limits the result set to performance data no later than this date | Rejects request | end=2017-01-02 |
country |
Comma-separated list of ISO 3166-1 Alpha-2 country codes | Returns only performance data matching the listed countries | Returns all countries |
country=US,CA,AU |
applicationId |
Comma-separated list of Vungle Application IDs to return | Returns only performance data for the listed applications | Returns all applications |
applicationId=586e201e242e3fd308000220,585849c3756684a50c0000a0 |
incentivized |
‘true’/’false’ or 1/0 |
Returns only performance data for incentivized or non-incentivized traffic Note: Rewarded ads are in some cases referred to as incentivized ads; both terms always refer to the same kind of ad. In the SDK code, we use the term 'incentivized'. |
Returns both incentivized and non-incentivized |
incentivized=false |
adType |
Comma-separated list of Vungle ad types to return |
Returns only performance data for the listed ad types. |
Returns all ad types. | adType=video |
adSize |
Comma-separated list of Vungle ad sizes to return | Returns only performance data for the listed ad sizes. | Returns all ad sizes. | adSize=320x50 |
Dimensions Parameter
Use dimensions to make your reports more or less granular. Send dimensions as a comma-separated list under a dimensions parameter. If you do not explicitly request a dimension, Vungle does not break the report down by that dimension.
Using the Dimensions Parameter
| Parameter name | Format | Example |
dimensions |
Comma-separated list of specific strings, listed in the table below |
|
Available Dimensions
| Dimension name |
Returns | Example return | ||||
platform |
Grouped by platform string |
|
||||
application |
Grouped by Vungle Application ID and name |
|
||||
placement |
Grouped by Placement ID and name. For apps still using Vungle SDK v. 4.1 and below, which do not support placements, placement id and placement name will display as null in our reporting, but aggregations such as views and publisher revenue will still be accurate. That is, non-updated devices will still be shown in the reports, but without placement breakdowns, which will be null. |
|
||||
date |
Grouped by date. |
|
||||
country |
Grouped by country. |
|
||||
incentivized |
Grouped by incentivized traffic. Note: Rewarded ads are in some cases referred to as incentivized ads; both terms always refer to the same kind of ad. In the SDK code, we use the term 'incentivized'. |
|
||||
adType |
Grouped by ad type. |
|
||||
adSize |
Grouped by ad size. |
|
For dimensions requiring a name lookup (for example, Application Name), if Vungle is unable to retrieve the lookup, we return an 'Unknown' string in place of the name.
Aggregates Parameter
Use aggregates to define which performance data interests you. Send aggregates as a comma-separated list under an aggregates parameter. If an aggregate is not in the list, Vungle assumes that you do not wish to receive that data.
Using the Aggregates Parameter
| Parameter name | Format | Example |
aggregates |
Comma-separated list of specific strings, listed in the table below |
|
Available Aggregates
| Dimension name |
Returns |
impressions |
integer |
views |
integer |
completes |
integer |
clicks |
integer |
revenue |
float |
ecpm |
(publisher revenue * 1000 / views) as a float |
Sample Queries and Responses
Example 1: JSON Revenue
Request
curl -i -H "Authorization: Bearer [API KEY]" -H "Vungle-Version:1" -H "Accept:application/json" -X GET "https://report.api.vungle.com/ext/pub/reports/performance?dimensions=date,country,platform&aggregates=views,revenue&start=2020-03-01&end=2020-03-05"
Response
[
{
"platform" : "iOS",
"date": "2020-03-01",
"country": "US",
"views": 1234,
"revenue": 123.0,
"ecpm": 99.67,
},
{
"platform" : "iOS",
"date": "2020-03-01",
"country": "CA",
"view": 35,
"revenue": 2.0,
"ecpm": 57.14,
},
...
]
Example 2: CSV Revenue
Request
curl -i -H "Authorization: Bearer [API KEY]" -H "Vungle-Version:1" -H "Accept:text/csv" -X GET "https://report.api.vungle.com/ext/pub/reports/performance?dimensions=date,country,platform&aggregates=views,revenue&start=2020-03-01&end=2020-03-05"
Response
Platform,date,country,views,revenue
ios,2020-03-01,US,1234,123.0
ios,2020-03-01,CA,35,2.0
...
Example 3: Placement
Request
curl -i -H "Authorization: Bearer [API KEY]" -H "Vungle-Version:1" -H "Accept:application/json" -X GET
"https://report.api.vungle.com/ext/pub/reports/performance?dimensions=placement&aggregates=views,revenue&start=2020-03-01&end=2020-03-05"
Response
[
{
"placement id" : "12345678",
"placement name": "level 3",
"views": 1234,
"revenue": 123.0
}
]