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.

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

The campaign report output contains both inventory and campaign level data. This report includes attempts, impressions, conversions, 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.

1.2 API Workflow

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

Publishers can retrieve daily reports and specify a date in the fetcher request. Reports for the previous day will be available at 2PM 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 through the ‘Enable data access through API’ checkbox in the Reports page of the MoPub UI.

After it is enabled, you can obtain your API and report keys by selecting the ‘View API Access Details’ link in the Reports page. Customers will also have the ability to reset their API Key in this modal.

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

publisher-reporting-api-1

publisher-reporting-api-2

2.1 Required Parameters

Request Field Definition
account_key Deprecated. Use api_key instead
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

2.2 Format

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

Must be a secure request

2.3 Sample Request

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

3.1 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 Header Dimensions

Dimension Definition
AdUnit Format Format of the adunit
AdUnit Adunit name as entered in the MoPub UI
AdUnit ID ID of the adunit
App App name as entered in the MoPub UI
App ID ID of the app
Country Two Digit short code (ISO 3166) of the country for which the data is desired
Day Format YYYY-MM-DD UTC timezone
Device Device
OS Operating system

3.2.2 Header Metrics

Dimension Definition
Requests An attempt to MoPub adserver to fill an impression. This will only be available in the inventory report
Impressions Number of times an ad is served
Clicks Number of times an ad is clicked
Revenue Revenue generated. This will be “0” for networks
CTR Click-through rate of an ad. The number of times the click is made on the ad divided by the number of impressions.
Conversions Only applicable to publishers who use the MoPub conversion tracking feature with the MoPub SDK. A customer action that has value on your app. Conversion tracking is used to properly measure the effectiveness of cross-promotions and direct sold advertisements. The conversion rate is the number of app conversions divided by the total number of ad clicks that can be tracked to a conversion.

3.3 Campaign Report

Dimension Definition
AdUnit Format Format of the adunit
AdUnit Adunit name as entered in the MoPub UI
AdUnit ID ID of the adunit
App App name as entered in the MoPub UI
App ID ID of the app
Country Two Digit short code (ISO 3166) of the country for which the data is desired
Creative Creative name as entered in the MoPub UI
Creative ID ID of the Creative
Day Format YYYY-MM-DD. UTC timezone
Device Device
Line Item Line item name. For network-segments, this will be “{network_name} {segment_name}”
Line Item ID ID of the line item
Line Item Type Type of ad source. Values may be “Backfill Promotional”, “Guaranteed”, “Network”, “Non-Guaranteed”, “ Private Marketplace”, “Promotional”, “Marketplace”
Priority Line item priority
Network Network name. For network segments, custom network and custom native network names are derived from the title field in the network creation page. For custom network or custom native network line items, the values are derived from the ‘Name’ input field in the line item creation page
Order Order name. For network-segments, this will be “{network_name} {segment_name}”
Order ID ID of the Order
OS Operating System
Segment Name of the segment the data is associated with. Segment name will be ‘N/A’ for line items
Segment ID ID of the segment the data is associated with. Segment ID will be ‘N/A’ for line items
Dimension Definition
Attempts An attempt to an ad network or Marketplace to fill an impression. This will only be available in the campaign report
Impressions Number of times an ad is served
Clicks Number of times an ad is clicked
Revenue Revenue generated. This will be “0” for networks
CTR Click-through rate of an ad. The number of times the click is made on the ad divided by the number of impressions.
Conversions Only applicable to publishers who use the MoPub conversion tracking feature with the MoPub SDK. A customer action that has value on your app. Conversion tracking is used to properly measure the effectiveness of cross-promotions and direct sold advertisements. The conversion rate is the number of app conversions divided by the total number of ad clicks that can be tracked to a conversion.
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. Please click “View API Access Details” at the top of https://app.mopub.com/reports/custom/ to see 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 2PM noon UTC on the following day. N/A
422 Data is not available for that date. There is not data for this date

FAQ

  1. 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.
  2. 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
  3. Why am I seeing zeroes in the revenue column?
    • Currently MoPub does not calculate network revenue
  4. What time will my reports be ready?
    • Reports will be ready at 2PM UTC
  5. Are historical reports updated with more finalized data?
    • The data is finalized as soon as it is made available.

Last updated May 31, 2018

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.

© 2018 MoPub Inc.