MoPub Analytics API

Overview

This API gives 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

The API is composed of a synchronous and an asynchronous endpoint. 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.

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 and value set to your 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.

API methods

Each API request sent must include a valid API Key as a header name x-api-key and value set to your API key.

Available date 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.

Synchronous data fetch

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.

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

Asynchronous data fetch

Use the below endpoints to fetch data asynchronously and check the status. It will accept HTTPS requests using POST. Use the data schema below for the body of the request. The response will be JSON.

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 data 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.

{
  "start": "string",
  "end": "string",
  "dimensions": "string",
  "metrics": "string",
  "filters": [
    {
      "field": "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
}
{
  "dataset": "dataset-1",
  "start": "yyyy-MM-DD",
  "end": "yyyy-MM-DD",
  "dimensions": [
    "dimension-1",
    "dimension-2",
    "dimension-3",
  ],
  "metrics": [
    "metric-1",
    "metric-2",
    "metric-3"
  ],
  "filters": [
    {
      "field": "dimension-1", 
      "operator": "=", 
      "value": "value-1"
    },
    {
      "field": "dimension-2", 
      "operator": "in", 
      "values": ["value-1", "value-2", "value-3"]
    }
  ],
  "sort": [
    {
      "dimension": "dimension-1",
      "order": "asc"
    },
  ]
}

Field Definitions

Name Description Required Field type
start Start date for the report. Example: 2020-01-24T05 yes string
end 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
  • - coming soon
  • 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 November 16, 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.)