MoPub Analytics API

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

Overview

This project is currently in beta testing.

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 an endpoint 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 name x-api-key.

You can do so by visiting your “Settings” which can be found by clicking on your username in the upper right corner of demand.mopub.com. 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.

Important

  • Only account Administrators can generate Keys.
  • You can create up to 10 active Keys. All keys are read and write.
  • This is the only time that the API key is visible. MoPub does not store these keys; if the key is lost, we will not be able to provide it again. A new Key must be generated.
  • Keys will auto-expire after 6 months, once a key is expired it can no longer be used to perform any functionality on the API. A new one must be created and used for future API usage.
  • Keys can also be deleted from your “Account settings” page prior to the 6-month expiration date, once deleted the key will no longer be valid.
  • Please be mindful when sharing API keys with others to ensure the security of your data and confidential information.

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 https://api.mopub.com/v2/demand/data - optional parameter, cube={cube} is supported for filtering.

Using Synchronous or Asynchronous endpoints

Synchronous endpoint

Use this endpoint to fetch data synchronously.

POST https://api.mopub.com/v2/demand/data/synchronous?cube={cube}&bidders={bidders_ID} - see “Metric and Dimension” table below for avaliable data cubes. Remember to authenticate by passing x-api-key with you API Key as a header.

Asynchronous endpoint

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

POST https://api.mopub.com/v2/demand/data/asynchronous?cube={cube}&bidders={bidders_IDs} - see “Metric and Dimension” table below for avaliable data cubes. Bidders will accept a comma seperated list of bidder ids. Remember to authenticate by passing x-api-key with you API Key as a header.

GET https://api.mopub.com/v2/demand/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 in the JSON response. Remember to authenticate by passing x-api-key with you API Key as a header.

Example

[
  {
    "job_id": "12345",
    "job_status": "PROCESSING",
    "output_url": "Not Available",
  },
  {
    "job_id": "23456",
    "job_status": "SUCCESS",
    "output_url": "http://ton.twitter.com/23456"     
  },
  {
    "job_id": "34567",
    "job_status": "FAILED",
    "output_url": "Not Available"
  }
]

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
Max metrics per query 5 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": [
        "App ID",
        "App Name"
    ],
    "metrics": [
        "Uniques",
        "Auctions Cleared",
        " App ID"
    ],
    "filters": [
        {
            "field": "App ID",
            "operator": "=",
            "value": "aecbbab9b8ff43bc8cd808e160224cf7"
        }
    ],
    "sort": [
        {
            "field": "Auctions Cleared",
            "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 array
metrics Comma separated list of metric fields to retrieve data for. yes string array
filters List of filter operations expressed as json structures with specific list of supported operators (=, like, not in, in). Max of 5 per query. no JSON list
sortBy List of fields to sort the data by expressed as json structures. Max of 5 per query. 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.

Data cube Dimensions Metrics
demand_bids_cube
  • Day
  • Ad Size
  • Adomain
  • App Or Site
  • Bid Outcome
  • Bid Price
  • Bidder Name
  • Bid Response Ad Size
  • Buyer Seat
  • Country
  • Creative ID
  • Creative MRAID
  • Creative Video Response
  • Gender
  • Has Device ID
  • Has Location
  • Has MRAID
  • Interstitial Playables Enabled
  • OS
  • Publisher
  • Response Deal ID
  • Response Inventory Package
  • UA Device
  • Video Format Enabled
  • Video Inventory Enabled
  • Viewability Measurable
  • Viewability Vendors Response
  • Bidder Id
  • App/Site ID
  • App/Site Name
  • Global Aid
  • Average Bid
  • Buyer Clear Rate
  • CTR
  • Clicks
  • Impressions Filled
  • Live Bid Responses
  • Non-Zero Bid Rate
  • Nonzero Bids
  • Spend
  • Survival Rate
  • Video Companion Ad Clicks
  • Video Companion Ad View
  • Video Complete
  • Video Completion Rate
  • Video First Quartile
  • Video Midpoint
  • Video Start
  • Video Third Quartile
  • Win Rate
  • Winning Bids
demand_auctions_cube
  • Day
  • Ad Size
  • Adomain
  • Age Range
  • App Or Site
  • App/Site ID
  • App/Site Name
  • Bidder Name
  • Buyer ID
  • Buyer Seat
  • Campaign ID
  • Connection Type
  • Consent Status
  • Country
  • Creative ID
  • Creative MRAID
  • Creative Type
  • Creative Video Served
  • Device
  • Gender
  • Global Aid
  • Has DNT
  • Has Device ID
  • Has Location
  • Has MRAID
  • Impression Latency
  • Interstitial Playables Enabled
  • OS
  • OS Version
  • Publisher ID
  • Publisher Name
  • Request Video Duration
  • Response Deal ID
  • Response Video Duration
  • SDK Version
  • Tag ID
  • Time
  • Video Format Enabled
  • Video Inventory Enabled
  • Auctions Cleared
  • Bid Average
  • Bid Depth
  • Clicks
  • Competitive Factor
  • CTR
  • eCPC
  • eCPM
  • Spend Estimate
  • Uniques
  • Video Companion Ad Clicks
  • Video Companion Ad View
  • Video Complete
  • Video Completion Rate
  • Video First Quartile
  • Video Midpoint
  • Video Start
  • Video Third Quartile

Last updated July 22, 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.)