Publisher Reporting API 2.0

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 Liftoff 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.
• Time zones: All data is reported in UTC. The Publisher Reporting API does not support other time zones.
• In the event of no data: Please note that if there is no data available for your query, Liftoff 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 Liftoff returns all results for that filter. 

Note that the Liftoff 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 country=US,CA country=US,CA,AU
applicationId	Comma-separated list of Liftoff 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
adType	Comma-separated list of Liftoff ad types to return	Returns only performance data for the listed ad types.	Returns all ad types.	adType=video
adSize	Comma-separated list of Liftoff 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, Liftoff 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 Liftoff Application ID and name	application id application name 58086457cdf5f9eb6d000060 Sonic Dash
placement	Grouped by Placement ID and name. For apps still using Liftoff 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 2020-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
adType	Grouped by ad type.	adType video,mrec,banner
adSize	Grouped by ad size.	adSize 320x50

For dimensions requiring a name lookup (for example, Application Name), if Liftoff 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, Liftoff 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,ecpm

 

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