Reporting API 2.0 for Publishers

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 Reporting API 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
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. 

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

country=US,CA

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

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=true

incentivized=false

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

dimensions=platform

dimensions=application,date,country 

 

Available dimensions  

Dimension 
name
 
Returns  Example return
platform Grouped by platform string
platform
iOS
application  Grouped by Vungle Application ID and name
application id application name
58086457cdf5f9eb6d000060 Sonic Dash
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.

placement id placement name
12345678 Level 3
date  Grouped by date 
date
2017-01-01
country  Grouped by country
country
US
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'.

incentivized
true
false

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

aggregates=views

aggregates=views,installs,ecpm 

 

Available aggregates  

Dimension 
name
 
Returns 
views integer
completes  integer
clicks  integer 
revenue  integer
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=2017-03-01&end=2017-03-05"

Response


[
    {
        "platform" : "iOS",
        "date": "2017-03-01",
        "country": "US",
        "views": 1234,
        "revenue": 123.0,
        "ecpm": 99.67,       
    },
    {
        "platform" : "iOS",
        "date": "2017-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:application/json" -X GET "https://report.api.vungle.com/ext/pub/reports/performance?dimensions=date,country,platform&aggregates=views,revenue&start=2017-03-01&end=2017-03-05"

Response


Platform,date,country,views,revenue
ios,2017-03-01,US,1234,123.0
ios,2017-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=2017-03-01&end=2017-03-05"

Response


[
    {
        "placement id" : "12345678",
        "placement name": "level 3",
        "views": 1234,
        "revenue": 123.0       
    }
]
Have more questions? Submit a request

Comments