MoPub Analytics API

The following is a proposal for discussion and feedback purposes only, and is subject to change.

Overview

With this project, we want to give customers the flexibility to fetch and handle their data as per their own needs by providing programmatic access so they don’t need to manually download data from MoPub Analytics or parse scheduled reports.

High Level Approach

At a high level, we will expose a synchronous and an asynchronous endpoint to external customers. The sync endpoint will serve quick interactive use-cases and provide access to a limited number of fields per query for recent dates only. The asynchronous endpoint will handle larger requests that may take a longer time to process and will return a job ID that can be used to fetch the resulting data once complete.

We will also include endpoints to track the status of asynchronous jobs and check the latest data availability of each dataset.

Authentication

The first step to taking advantage of the API is to create an API key to use for authenticating requests. Each API request sent must include a valid API Key as a header.

You will first need to create an API Key. You can do so by visiting your “Account Settings” tab on mopub.com, and scroll down to the “Publisher Management API Keys” section. Once here, you can create a new API key by clicking on the “New API key” button. A dialogue-box will appear, where you can name your API key.

After you have named your key and clicked on the “Create new API key” button to proceed, your new API key will appear in the dialogue box as shown below. Please note down this API key in a safe place, as it will only be shown to you once and cannot be recovered.

Fetching data reports

Available data ranges

This endpoint will return the date range available for all cubes available to the current user. It will accept https requests using GET.

GET api.mopub.com/v2/data - optional parameter, cube={cube} is supported for filtering.

Using Synchronous or Asynchronous endpoints

Synchronous endpoint

Use this endpoint to fetch data synchronously. The response will be JSON.

POST api.mopub.com/v1/data/synchronous/:cube - required parameter, cube={cube}- see “Metric and Dimension” table below for avaliable data cubes.

Asynchronous endpoint

Use the below endpoints to fetch data asynchronously and check the status.

POST api.mopub.com/v1/data/asynchronous/:cube - required parameter, cube={cube} - see “Metric and Dimension” table below for avaliable data cubes.

GET api.mopub.com/v1/data/status- optional parameters, jobId={jobId}&jobStatus={jobStatus}, are support for filtering. If no parameters are provided then all job status for jobs started in the last 24 hours will be return. Once complete a url to download the csv report is provided.

Limitations

The below limitations will help you decide rather to use the synchronous or asynchronous endpoint.

  Synchronous Asynchronous
Account level rate limits 10 request per min 10 jobs per day
Available ddata Last 14 days Last 13 months
Max days per reqeust 14 days 90 days
Max dimensions per query 2 10
Response Data in JSON format Job ID, once complete a link to download the csv report is provided
Row limit 1,000 10,000,000
Supported data cubes auctions, platform-performance auctions, platform-performance

Data schema

Use the below data schema for the body of the POST request to fetch data.

{
  "startDate": "string",
  "endDate": "string",
  "dimensions": "string",
  "metrics": "string",
  "filters": [
    {
      "dimension": "string",
      "operator": "string",
      "value": "string"
    }
  ],
  "sortBy": [
    {
      "field": "string",
      "order": "string",
    }
  ],
  "limit": "integer"
}
   

Example

{
    "start": "2021-06-01",
    "end": "2021-06-07",
    "dimensions": [
        "Adunit ID",
        "Adgroup Name"
    ],
    "metrics": [
        "Adserver Impressions",
        "Adserver Clicks"
    ],
    "filters": [
        {
            "field": "Adunit ID",
            "operator": "=",
            "value": "aecbbab9b8ff43bc8cd808e160224cf7"
        }
    ],
    "sort": [
        {
            "field": "Adserver Impressions",
            "order": "Desc"
        }
    ],
    "limit": 1000
}

Field Definitions

Name Description Required Field type
startDate Start date for the report. Example: 2020-01-24T05 yes string
endDate End date for the report. Example: 2020-01-24T05 yes string
dimensions Comma separated list of dimension fields to retrieve data for. yes string
metrics Comma separated list of metric fields to retrieve data for. yes string
filters List of filter operations expressed as json structures with specific list of supported operators (=, like, not in, in) no JSON list
sortBy List of fields to sort the data by expressed as json structures. no JSON list
limit Maximum number of rows to return. If not specified, the row limit will be set to the max sync query row limit by default. no integer

Metric and Dimension

Definitions for the below metrics and dimensions can be found here. Data for the last 13 months is supported. Use the “time” dimension for granualarity which is hourly.

Data cube Dimensions Metrics Granularity
publisher_auctions_cube
  • Time - will aggregate at granularity level
  • Ad Size
  • Adgroup Id
  • Adgroup Name
  • Adgroup Priority
  • Adomain
  • Adunit
  • Adunit Name
  • Age Range
  • App Version
  • Application
  • Bidder Name
  • Buyer Seat
  • Consent Status
  • Consent Status Details
  • Country
  • Creative ID
  • Creative MRAID
  • Creative Video Served
  • Device
  • Gender
  • Global Aid
  • Has Device ID
  • Has Location
  • Impression Latency
  • Interstitial Playables Enabled
  • Inventory Package
  • OS
  • OS Version
  • Order Advertiser
  • Order Id
  • Order Name
  • Price Floor
  • Publisher
  • Publisher Id
  • Request Video Duration
  • Response Deal ID
  • Response Video Duration
  • SDK Version
  • Site
  • Time
  • Video Inventory Enabled
  • Viewability Vendors Response
  • Winning Creative Ad Size
  • Auctions
  • Auctions Won
  • Bid Avg
  • Bid Depth
  • Clear Rate
  • Cleared
  • Clicks
  • CTR
  • eCPM
  • Net Revenue
  • Survival Rate
  • Uniques
  • Video Complete
  • Video Completion Rate
  • Video Midpoint
  • Video Start
  • Win Rate
  • Winning Bid Avg
Hourly
publisher_platform_performance_cube
  • Time - will aggregate at granularity level
  • Account Key
  • Publisher Name
  • App Id
  • App Name
  • Adgroup Type
  • Adgroup Network Type
  • Adgroup Id
  • Adgroup Name
  • Adunit Id
  • Adunit Name
  • Adunit Format
  • Country
  • OS
  • Order Id
  • Order Advertiser
  • Order Name
  • NR Network Type
  • SDK Version
  • Ad Requests
  • AdServer Attempts
  • AdServer Clicks
  • AdServer CTR
  • AdServer eCPM
  • Adserver Impressions
  • AdServer Revenue
  • Attempt Responses
  • Clk DAU
  • Fill Rate (Demand)
  • Fill Rate (Inv)
  • Fills
  • Imp DAU
  • Latency (Demand)
  • NR eCPM
  • NR Impressions
  • NR Revenue
  • Render Rate
  • Req DAU
  • Show Rate (Demand)
  • Show Rate (Inv)
  • Uniques
  • Waterfall Depth
  • Waterfall Latency
Daily

Last updated June 17, 2021

TWITTER, MOPUB, and the Bird logo are trademarks of Twitter, Inc. or its affiliates. All third party logos and trademarks included are the property of their respective owners.

© 2021 MoPub (a division of Twitter, Inc.)