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

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/data - optional parameter, cube={cube} is supported for filtering.

Synchronous data fetch

Use this endpoint to fetch data synchronously. It will accept HTTPS requests using POST. The response will be JSON.

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

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/data/asynchronous?cube={cube} - required parameter, cube={cube} - see “Metric and Dimension” table below for avaliable data cubes.

GET https://api.mopub.com/v2/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.

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 31 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": [
    {
      "dimension": "string",
      "operator": "string",
      "value": "string"
    }
  ],
  "sort": [
    {
      "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
start Start date for the report. Example: 2020-01-24 yes string
end End date for the report. Example: 2020-01-24 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
sort 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 Granularity
publisher_auctions_cube
  • Day
  • Ad Size
  • Adgroup Id
  • Adgroup Name
  • Adgroup Priority
  • Adomain
  • Adunit ID
  • Adunit Name
  • Age Range
  • App Version
  • App Name
  • 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
  • - coming soon
  • Video Complete
  • Video Completion Rate
  • Video Midpoint
  • Video Start
  • Win Rate
  • Winning Bid Avg
Daily
publisher_platform_performance_cube
  • Day
  • 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
  • - coming soon
  • Waterfall Depth
  • Waterfall Latency
Daily

Last updated August 24, 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.)