MoPub Publisher Reporting API

This guide outlines the API specifications to pull daily direct, network, and Marketplace stats and is intended for use by software engineers, system architects, and product or project managers.

1.1 Overview

The MoPub Reporting API supports two separate CSV outputs where publishers can retrieve inventory or campaign performance data.

  • Inventory report: The inventory report output only contains information about apps and ad units. This report includes requests, impressions, clicks, and CTR metrics. Customers can calculate inventory fill rate based on request data. Note that ad source information is not available in this report.

  • Campaign report: The campaign report output contains both inventory- and campaign-level data. This report includes attempts, impressions, clicks, and CTR metrics. Customers can calculate ad source fill rate based on attempts to an ad source to fill an impression. Note that this CSV output does not contain an inventory request metric.

Notes:

  • Metadata will not be included for archived or deleted line items.
  • Data prior to January 25, 2021 is not available via the API.

1.2 API Workflow

Users will make a GET request using the request parameters and endpoint outlined in Section 2. This URL will return a 302 redirect response. The link to download the report will be returned in the response location header. Download links expire after 30 days.

Publishers can retrieve daily reports and specify a date in the fetcher request. Reports for the previous day will be available at 10:00am UTC and customers can retrieve data up to the day before the API was enabled in the MoPub UI. The data is finalized as soon as it is made available.

1.3 Granting Permission to Access the Reporting API

In order to retrieve data, the API must first be enabled using the Enable data access through API checkbox in the Reports tab of the MoPub Publisher UI.

Publisher Reporting API

After it is enabled, you can obtain your API and report keys by clicking View API Access Details in the Reports tab. You can reset your API Key in this modal.

Publisher Reporting API Keys

If you still need to access your Account Key, please contact your account manager.

2.1 Request and Response Format

2.1.1 Request Structure (Must Be Secure)

Endpoint:

https://app.mopub.com/reports/custom/api/download_report?report_key=[REP_KEY]&api_key=[API_KEY]&date=[YYYY-MM-DD]

Required parameters:

Request Field Definition
api_key Publisher unique authentication mechanism
report_key ID of the report to fetch. MoPub provides publishers with an inventory report ID and a campaign report ID
date Date of the report. Format YYYY-MM-DD

Example Request:

https://app.mopub.com/reports/custom/api/download_report?report_key=317b8515f5b64868b771ba03074daa8&api_key=18427072dad334e3b089a0446225e1e&date=2016-06-12

2.1.2 Response Structure

The response will be in a CSV format with the following structure:

Row Type Content
Header Row A single row containing column headers of the report
Data Rows Multiple rows containing data values

3.2 Inventory Report

3.2.1 Inventory Report Header Dimensions

Dimension Definition
Adgroup Network Type A dimension defined by MoPub. To review more accurate data for a Supported Network that has network reporting enabled, refer to the second bullet point in this section.
Adunit Format Format of the ad unit. A dimension defined by MoPub. Formats are listed here, with legacy sizes in parentheses: banner (320x50), native, medium_rectangle (300x250), full, rewarded_video, banner (728x90), full (full_tablet), custom.
Adunit ID ID of the ad unit.
Adunit Name Ad unit name as entered in the MoPub UI.
App ID ID of the app.
App Name App name as entered in the MoPub UI.
Country Three-digit short code (ISO 3166) of the country for which the data is desired.
Day Format YYYY-MM-DD UTC time zone.
Device Model Model of the device.
OS Operating system.
SDK Version MoPub SDK Version.

3.2.2 Inventory Report Header Metrics

Metric Definition
Adserver Attempts The number of times MoPub made an ad attempt to an ad demand source (network, Marketplace, Direct Serve) for a given ad request. Some of these attempts may be counted more than once as the attempt moves through the mediation waterfall. The attempt includes both client and server sides of the attempt, based on demand source type.
Adserver Clicks Number of times an ad is clicked. This is reported by MoPub.
Adserver Impressions Total number of times the ad was shown to users. This is reported by MoPub.
Adserver Requests The number of times an ad unit has requested an ad. This is reported for all demand source types.
Adserver Revenue Estimated revenue reported by MoPub ad server for all demand sources (network, Direct Serve, Marketplace). It can be broken down into a variety of dimensions, such as ad unit, format, ad group, app, etc. This metric includes the revenue of network, and it is estimated and calculated based on:
- MoPub impressions
- Auto CPM or manually-entered eCPM
Direct Serve and Marketplace revenue are accurate revenues reported by the MoPub ad server. This is not used for billing.
CTR Click-through rate of an ad. The number of times the click is made on the ad divided by the number of impressions.
Fill Rate (Demand) The proportion of Attempts that resulted in Fills. Formula: Fills / Attempt Responses.
Fill Rate (Inventory) The proportion of Fills to Ad Requests. This represents how often Ad Requests end up in Fills. Formula: Fills / Requests.
Fills Fills (for example, Successful Loads) is the total number of creatives that successfully loaded on the device. This is before the impression renders on the device.
Show Rate (Demand) The proportion of Attempt Responses that result in Impressions. Formula: Impressions / Attempt Responses.
Show Rate (Inventory) The Inventory show rate metric measures the number of times an ad was shown to users (impressions) compared to the number of times an ad was requested from a specific ad unit (requests). Formula: Impressions / Requests.

3.3 Campaign Report

3.3.1 Campaign Report Header Dimensions

Dimension Definition
Adgroup ID The internal MoPub ID for the ad group (Line Item). This dimension includes both the Line Item and Segment.
Adgroup Name The name of the ad group (Line Item). This dimension includes both the Line Item and Segment.
Adgroup Network Type A dimension defined by MoPub. To review more accurate data for a Supported Network that has network reporting enabled, refer to the second bullet point in this section.
Adgroup Priority Adgroup (Line Item) priority.
Adgroup Type A dimension defined by MoPub. Individual Ad Group Types are: backfill_promo, Unavailable, non_gtee, gtee, network, marketplace, advanced_bidding_mpx, mpx_line_item, pmp_line_item, advanced_bidding_network
Adunit Format A dimension defined by MoPub. Formats are listed here, with legacy sizes in parentheses: banner (320x50), native, medium_rectangle (300x250), full, rewarded_video, banner (728x90), full (full_tablet), custom.
Adunit ID ID of the ad unit.
Adunit Name Ad unit name as entered in the MoPub UI.
App ID ID of the app.
App Name App name as entered in the MoPub UI.
Country Three-digit short code (ISO 3166) of the country for which the data is desired.
Creative ID ID of the Creative.
Creative Name Creative name as entered in the MoPub UI.
Day YYYY-MM-DD format, UTC time zone.
Device Model Device model.
Order Name Order name. For network-segments, this is ‘{network_name} {segment_name}’.
Order ID ID of the Order.
OS Operating system.
SDK Version MoPub SDK version.

3.3.2 Campaign Report Header Metrics

Metric Definition
Adserver Attempts The number of times MoPub made an ad attempt to an ad demand source (network, Marketplace, Direct Serve) for a given ad request. Some of these attempts may be counted more than once as the attempt moves through the mediation waterfall. The attempt includes both client and server sides of the attempt, based on demand source type.
Adserver Clicks Number of times an ad is clicked. This is reported by MoPub.
Adserver Impressions Total number of times the ad was shown to users. This is reported by MoPub.
Adserver Requests The number of times an ad unit has requested an ad. This is reported for all demand source types.
Adserver Revenue Estimated revenue reported by MoPub ad server for all demand sources (network, Direct Serve, Marketplace). It can be broken down into a variety of dimensions, such as ad unit, format, ad group, app, etc. This metric includes the revenue of network, and it is estimated and calculated based on:
- MoPub impressions
- Auto CPM or manually-entered eCPM
Direct Serve and Marketplace revenue are accurate revenues reported by the MoPub ad server. This is not used for billing.
CTR Click-through rate of an ad. The number of times the click is made on the ad divided by the number of impressions.
Fill Rate (Demand) The proportion of Attempts that resulted in Fills. Formula: Fills / Attempt Responses.
Fill Rate (Inventory) The proportion of Fills to Ad Requests. This represents how often Ad Requests end up in Fills. Formula: Fills / Requests.
Fills Fills (for example, Successful Loads) is the total number of creatives that successfully loaded on the device. This is before the Impression renders on the device.
Show Rate (Demand) The proportion of Attempt Responses that result in Impressions. Formula: Impressions / Attempt Responses.
Show Rate (Inventory) The Inventory show rate metric measures the number of times an ad was shown to users (impressions) compared to the number of times an ad was requested from a specific ad unit (requests). Formula: Impressions / Requests.

3.4 Error Messages

HTTP Status Error Message Description
400 Missing required URL parameter: {PARAM_NAME} N/A
400 Date parameter is malformed. Date must be in YYYY-MM-DD format. N/A
422 Invalid api_key. (Either the api_key you provided was never correct or perhaps it was reset. Click View API Access Details at the top of the Reports tab to access your api_key.) N/A
422 Invalid report_key. N/A
422 Data not available before {START_DATE}. User is trying to fetch data prior to the day before the API checkbox was enabled in the MoPub UI.
422 Data is not available for that date yet. Data is available after 10:00am UTC on the following day. N/A
422 Data is not available for that date. There is not data for this date.

4.0 Changelog

This is the changelog of the data fields between old and new reporting systems for MoPub scheduled reports and API reports.

What Changed Old System New System
No changes OS OS
Country Country
Order Order
CTR CTR
Name was changed (field name in the spreadsheet and UI) App App Name
AdUnit Adunit Name
Line Item / Segment Adgroup Name
Line Item Type Adgroup Type
Creative Creative Name
Priority Adgroup Priority
Impressions Adserver Impressions
Attempts / Requests Adserver Requests
Adserver Attempts  
Clicks Adserver Clicks
Revenue Adserver Revenue
Note: This is the estimated revenue that includes all demand sources.
Format of the data was changed Country: 2-letter country code (US, FR) Country: 3-letter country code (USA, FRA)
Added new metrics - Fills
- Fill Rate (Inventory)
- Fill Rate (Demand)
- Show Rate (Inventory)
- Show Rate (Demand)
Added new dimensions - App ID
Note: This is new for email scheduled report/ad hoc report from UI. API reports from old and new systems both have App ID.
- Adunit ID
Note: This is new for email scheduled report/ad hoc report from UI. API reports from old and new systems both have Adunit ID.
- Order ID
Note: This is new for email scheduled report/ad hoc report from UI. API reports from old and new systems both have Order ID.
- Adgroup ID
Note: This is new for email scheduled report/ ad hoc report from UI. API reports from old and new systems both have Adgroup ID.(fka Line Item ID or Segment ID)
- Adgroup Network Type
Note: This is new for email scheduled report/ ad hoc report from UI. API reports from old and new systems both have Adgroup Network Type ID.(fka Line Item Type)
- Device Model
- SDK Versions
Removed metric or dimension Conversions
Note: Conversions metric was a legacy metric for cross-promotion / Direct Serve ads.
-
Device
Note: New dimension “Device Model” provides more detailed insight than “Device.”
-
Segment / Segment ID
Note: Segment / Segment ID are now consolidated into “Ad group / Ad group ID.”
-

FAQ

Can I pull historical data?

The API supports data for one day prior to the date the API checkbox was enabled in the MoPub UI. If there are dates when the API check box was not enabled then the data for those dates will not be availble. For example, if the checkbox is uncheck and then re-check X days later, the data for the X days on which it was unchecked with NOT be available.

What does ‘N/A’ represent?

‘N/A’ means there is no data tied to the header columns. You will see ‘N/A’ for the following:

  • Segment header row for line items since line items are associated with an Order, not a segment.
  • Creative and Creative IDs for line items or segments that do not have an associated creative, such as Marketplace or custom native networks.

What time will my reports be ready?

Reports will be ready at 10:00am UTC.

Are historical reports updated with more finalized data?

The data is finalized as soon as it is made available.


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