Advertiser Reporting API 2.0

Vungle Agent

November 09, 2022 03:27

Overview

The reporting API offers advertisers 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. You can find your Reporting API Key here.

Host

https://report.api.vungle.com/ext/adv/reports/spend

Authentication

Security is handled in the request header. Find your Reporting API Key in the Account page of the Liftoff Direct Dashboard. If you don't already have a Reporting 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, specified in the request header.
Date range: Historical information is available for up to six months. To retrieve older data, email your account manager or contact tech-support@vungle.com.
Time zone: UTC is our default time zone, and cannot be changed at this time.
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/spend

Filter Parameters

Use filter parameters to restrict the results to a subset of your spend data. Most filters are optional, and if they are excluded, Liftoff returns all results for that filter.

Parameter name	Format	Action	If Unavailable	Example
`start`	ISO8601 date	Limits the result set to data no earlier than this date	Rejects request	`start=2019-01-01`
`end`	ISO8601 date	Limits the result set to data no later than this date	Rejects request	`end=2019-01-02`
`country`	Comma-separated list of ISO 3166-1 Alpha-2 country codes	Returns only spend data matching the listed countries	Returns all countries	Returns all countries Returns all countries `country=US,CA,AU`
`applicationId`	Comma-separated list of Liftoff Application IDs to return	Returns only spend data for the listed applications	Returns all applications	`applicationId=586e201e242e3fd308000220` `applicationId=586e201e242e3fd308000220,585849c3756684a50c0000a0`
`campaignId`	Comma-separated list of Liftoff campaign IDs	Returns only data for the listed campaigns	Returns all campaigns	`campaignId=586e201e242e3fd308000220` `campaignId=586e201e242e3fd308000220,585849c3756684a50c0000a0`
`creativeId`	Comma-separated list of Liftoff creative IDs	Returns only spend data for the listed creatives	Returns all creatives	`creativeId=586e201e242e3fd308000220` `creativeId=586e201e242e3fd308000220,585849c3756684a50c0000a0`
`siteId`	Comma-separated list of publisher site IDs	Returns only spend data for the listed sites	Returns all publishers	`siteId=586e201e242e3fd308000220` `siteId=586e201e242e3fd308000220,585849c3756684a50c0000a0`
`accountId`	Comma-separated list of publisher account IDs	Returns only spend data for the listed accounts	Returns all accounts	`accountId=58e71dd7294039844b0001c7`
`placementId`	Comma-separated list of publisher placement IDs	Returns only spend data for the listed placements	Returns all placements	`placementId=5bc9877224291f02aee8741c`
`adType`	Comma-separated list of ad types	Returns only spend data for the listed ad types	Returns all ad types	`adType=banner,mrec,video,fullscreen`
`adSize`	Comma-separated list of ad sizes	Returns only spend data for the listed ad sizes	Returns all ad sizes	`adsize=728x90,default,320x50,300x50`

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 following table	dimensions=platform `dimensions=campaign,creative,date`

Available Dimensions

Dimension Name	Returns	Sample Return	Endpoints
`platform`	Grouped by platform string	platform `iOS`	`spend`
`account`	Grouped by Liftoff Account ID	account `5808AA57cdf5f9eb6d000060`	`spend`
`application`	Grouped by application ID and application Name	application ID `58086457cdf5f9eb6d000060` application name `Toy Blast iOS`	`spend`
`campaign`	Grouped by campaign ID and campaign Name	campaign ID `58086457cdf5f9eb6d000060` campaign name `Toy Blast iOS CA iPhone`	`spend`
`date`	Grouped by date	date `2019-01-01`	`spend`
`country`	Grouped by country	country `US`	`spend`
`creative`	Grouped by creative ID and creative name	creative ID `58086457cdf5f9eb6d000060` creative name `Toy Blast Landscape IEC`	`spend`
`site`	Grouped by publisher app object ID and publisher app name	site ID `58086457cdf5f9eb6d000060` site name `Sonic Dash iOS`	`spend`
`placement`	Grouped by `placement`	`placement_id 599306279c57ddf458005ee2`	`spend`
`adType`	Grouped by `adType`	`banner`	`spend`
`adSize`	Grouped by `adSize`	`728x90`	`spend`

For dimensions requiring a name lookup (for example, 'Site 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 no aggregate is 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 following table	`aggregates=views` `aggregates=views,installs,ecpm`

Available aggregates

Dimension Name	Returns	Endpoints
`views`	integer	`spend`
`completes`	integer	`spend`
`clicks`	integer	`spend`
`installs`	integer	`spend`
`spend`	integer	`spend`
`ecpm`	(spend * 1000 / views) as a float	`spend`
`eCPI`	(spend /install ) as a float	`spend`
`CTR`	(clicks/impressions) as a float	`spend`
`IR`	(installs/clicks) as a float	`spend`
`IPM`	(installs/impressions) *1000 as a float	`spend`

Example 1: JSON Spend


curl -i \
-H "Authorization: Bearer [API KEY]" \
-H "Vungle-Version:1" \
-H "Accept:application/json" \
-X GET "https://report.api.vungle.com/ext/adv/reports/spend?dimensions=date,country,platform&aggregates=views,spend&start=2019-01-01&end=2019-01-01"

[ 
 { 
  "platform" : "iOS", 
  "date": "2019-01-01", 
  "country": "US", 
  "views": 1234, 
  "spend": 123.0 
 }, 
 { 
  "platform" : "Android", 
  "date": "2019-01-01", 
  "country": "CA", 
  "view": 35, 
  "spend": 2.0 
 }, ... 
]

Example 2: CSV Spend

curl -i \
-H "Authorization: Bearer [API KEY]" \
-H "Vungle-Version:1" \
-H "Accept:text/csv" \
-X GET "https://report.api.vungle.com/ext/adv/reports/spend?dimensions=date,country,platform&aggregates=views,spend&start=2019-01-01&end=2019-01-01"

Platform,date,country,views,spend 
ios,2017-03-01,US,1234,123.0 
ios,2017-03-01,CA,35,2.0

Example 3: ID/Name Expansion

curl -i \
-H "Authorization: Bearer [API KEY]" \
-H "Vungle-Version:1" \
-H "Accept:application/json" \
-X GET "https://report.api.vungle.com/ext/adv/reports/spend?dimensions=campaign&aggregates=views,spend&start=2019-01-01&end=2019-01-01"

[
 {
  "campaign id" : "12345678",
  "campaign name": "test campaign 1",
  "views": 1234,
  "spend": 123.0       
 }
]