Skip to end of metadata
Go to start of metadata

Report Service

The Report Service is used to provide access to many different types of reports. It also ensures that each user types can only access the reports that are appropriate for that type. For example, network users have access to all report types, while advertiser and publisher users only have access to a few.

The available metrics vary depending on the report type, but can include how much money was spent on inventory, the number of impressions seen and/or sold, revenue earned, and more. This document describes how to request and download data from the Report Service; it also describes how to get more information about each of the supported report types, as well as providing links to further documentation about each report type.

For more information about how to sync AppNexus data to your reporting database, see Bulk Reporting Feeds.

This is a read-only service; you will POST a JSON-formatted report request, but this will not alter any of the data stored on our servers.

On This Page

Report Types

Report Type

User Type

Description

Data Retention

Network Analytics
network_analytics

Network

General overview of what is happening. What's serving, what's doing well, on both buy and sell side.

Lifetime - some data at reduced granularity after 100 days

Network Billing
network_billing

Network

What you might need to bill advertisers, what you might be billed by publishers or AppNexus.

Lifetime - some data at reduced granularity after 100 days

Buying Billing Report
buyer_invoice_report

Network

Reporting for financial reconciliation with buying related charges.

Lifetime - some data at reduced granularity after 100 days

Selling Billing Report
seller_invoice_report
Network

Reporting for financial reconciliation with selling related charges.

Lifetime - some data at reduced granularity after 100 days

Network Advertiser Analytics
network_advertiser_analytics

Network

Network reporting on advertisers.

Lifetime - some data at reduced granularity after 100 days

Network Publisher Analytics
network_publisher_analytics

Network

Network reporting on publishers.

Lifetime - some data at reduced granularity after 100 days

Publisher Analytics
publisher_analytics

Network, Publisher

Reporting for what a publisher should see.

Lifetime - some data at reduced granularity after 100 days

Advertiser Analytics
advertiser_analytics

Network, Advertiser

Reporting for what an advertiser should see.

Lifetime - some data at reduced granularity after 100 days
Network Video Analytics
video_analytics_network
NetworkVideo event reporting across advertisers and publishers.One year
Network Advertiser Video Analytics
video_analytics_network_advertiser
NetworkVideo event reporting for a single advertiser.One year
Network Publisher Video Analytics
video_analytics_network_publisher
NetworkVideo event reporting for a single publisher.One year
Buyer Segment Performance Report
buyer_segment_performance
NetworkReporting on segment performance across campaigns and multiple advertisers.30 days
Seller Brand Review Report
seller_brand_review
NetworkReporting on brand performance across all of network's inventory.60 days
Publisher Brand Review Report
publisher_brand_review
PublisherReporting on brand performance across all of publisher's inventory.60 days

Network Creative Frequency & Recency
network_advertiser_frequency_recency

Network

Network reporting on creative frequency and recency for a single advertiser.

14 days

Advertiser Creative Frequency & Recency
advertiser_frequency_recency

Network, Advertiser

Reporting for what an advertiser should see about its creative frequency and recency.

14 days

Network Site Domain Performance
network_site_domain_performance

Network

Network reporting on domain performance across advertisers.

30 days

Site Domain Performance
site_domain_performance

Network, Advertiser

Reporting on domain performance for a single advertiser.

30 days

Seller Site Domain
seller_site_domain

Network

Reporting on what inventory is coming through a publisher.

7 days

Segment Loads
segment_load

Network

Network reporting on segments.

30 days

Attributed Conversions
attributed_conversions

Network

Network reporting on advertisers' attributed conversions.

33 days

Geo Analytics Report
geo_analytics

Network

Break down campaign delivery and performance by geographic area.

45 days

Network Carrier Analytics
network_carrier_analytics

Network

Report on buy-side and sell-side performance data based on mobile device carriers.

14 days

Network Device Analytics
network_device_analytics

Network

Report on buy-side and sell-side performance data based on devices where impressions were served.

14 days

Conversion Pixel Last Fire
pixel_fired

Network

Network reporting on the last fire date and time of advertisers' conversion pixels.

Lifetime
Completed Creative Audits Report
completed_creative_audits
NetworkNetwork report designed to give you insight into how your creatives are moving through the audit process90 days

Bulk Reporting Feeds
network_analytics_feed
clicktrackers

Network

The ability to sync our aggregated reports to your reporting database.

30 days
Data Usage Report
buyer_data_usage_analytics
NetworkNetwork report that give details on your usage of data provided by third parties (e.g., user segment providers), the costs of that data usage and line items/campaigns in which that data was used to target users.60 days

Buyer Deal Metrics
buyer_deal_metrics

Advertiser, NetworkKey information about deal metrics, performance, and rejection reasons that is relevant to buyers. 30 days

Seller Deal Metrics
seller_deal_metrics

Publisher, Networkkey information about deal metrics, performance, and rejection reasons that is relevant to sellers30 days

REST API for Viewing Metadata

Return meta data for all reports:
GET https://api.appnexus.com/report?meta

Return meta data for a particular report type:
GET https://api.appnexus.com/report?meta=REPORT_TYPE

JSON Fields

The meta array includes the following fields:

Field

Description

time_granularity

The granularity of time for which the report can provide data. Possible values: "hourly", "daily", "monthly", "yearly", or "lifetime". If "hourly" or "lifetime", data is available for year, month, day, and hour. If "daily", "monthly", or "yearly", data is available for only year, month, and day.

columns

The columns that can be requested. For each column, the name and type are listed in the JSON response.

filters

The columns that can be used as filters. For each column, the name and type are listed in the JSON response.

time_intervals

The time ranges for which the report can be run.

Some report types will allow you to run a report for a custom time frame. This can be done by setting the start_date and end_date fields in your report request.

Click here to view an example meta data response (using the network_analytics report)

REST API for Data Retrieval

Request a report:
POST https://api.appnexus.com/report
(report JSON)

Request the status of a report:
GET https://api.appnexus.com/report?id=REPORT_ID

Retrieve report data:
GET https://api.appnexus.com/report-download?id=REPORT_ID

Network users can run advertiser and publisher-level reports by appending advertiser_id=ADVERTISER_ID or publisher_id=PUBLISHER_ID to the query string.

JSON Fields

Field

Required on POST

Type

Description

report_type

yes

enum

This determines which information will be returned. Possible values:

  • "network_analytics"
  • "network_billing"
  • "buyer_invoice_report"
  • "seller_invoice_report"
  • "network_advertiser_analytics"
  • "network_publisher_analytics"
  • "network_site_domain_performance"
  • "advertiser_analytics"
  • "video_analytics_network"
  • "video_analytics_network_advertiser"
  • "video_analytics_network_publisher"
  • "buyer_segment_performance"
  • "seller_brand_review"
  • "publisher_brand_review"
  • "publisher_analytics"
  • "network_creative_search"
  • "publisher_creative_search"
  • "network_advertiser_frequency_recency"
  • "advertiser_frequency_recency"
  • "site_domain_performance"
  • "seller_site_domain"
  • "inventory_domain_analytics"
  • "inventory_source_analytics"
  • "inventory_daily_uniques"
  • "segment_load"
  • "attributed_conversions"
  • "pixel_fired"
  • "network_analytics_feed"
  • "clicktrackers"
  • "key_value_analytics"

timezone

No

string (50)

This determines which timezone the data will be reported in. For a list of possible timezone values, see API Timezones.

For the network_billing, network_analytics, network_advertiser_analytics, network_publisher_analytics, advertiser_analytics, and publisher_analytics report types, data older than 100 days will be reported in UTC. Also, report types that do not offer hourly data, such as network_site_domain_performance, site_domain_performance, and seller_site_domain will be reported in UTC.

filters

No

array

The list of filter objects to apply to the report. See step 1 of How to Run a Report below.

group_filters

No

array of objects

Allows you to specify an operation to perform on one or more filters. For example, if you're selecting total impressions grouped by campaign, you can use this field to filter out campaigns that don't have at least 10,000 impressions:

columns

yes

array of strings

The list of columns to include in the report. See step 1 of How to run a report below. At least one column must be specified.

row_per OR groups

No

array

Deprecated. By default, reporting results are automatically grouped by the dimensions in columns. Passing these fields has no effect.

For most reports, selected dimensions are grouped automatically. For example, if you include the columns "advertiser_id", "campaign_id", "creative_id", and "imps", each row of report data would show the impressions per advertiser, campaign, and creative combination.

start_date

No

string

The start date for the report.

  • For report types that offer hourly data, this must be formatted as "YYYY-MM-DD HH:MM:SS". However, note that MM:SS must be 00:00, as data is not available for minutes and seconds.
  • For report types that do not offer hourly data, this must be formatted as "YYYY-MM-DD".

end_date

No

string

The end date for the report.

The end_date is non-inclusive. For example, if you start a report at "2017-07-01 00:00:00" and end the report at "2017-07-01 23:00:00", your report will not include data from the last hour of the day. The correct way to retrieve this data would be to end the report at "2017-07-02 00:00:00".

  • For report types that offer hourly data, this must be formatted as "YYYY-MM-DD HH:MM:SS". However, MM:SS must be 00:00, as data is not available for minutes and seconds. For example, "2017-07-01 00:00:00" to "2017-07-02 00:00:00" would retrieve an entire day's data.
  • For reports aggregated across intervals longer than hourly (e.g., daily, weekly, etc.), the format must be "YYYY-MM-DD". For example, "2017-07-01" to "2017-07-02" would retrieve an entire day's data.

report_interval

No

enum

The time range for the report. Not all reports accept all intervals. See each report's documentation and metadata for details. Possible values:

  • current_hour
  • last_hour
  • today
  • yesterday
  • last_48_hours
  • last_2_days
  • last_7_days
  • last_14_days
  • month_to_yesterday
  • month_to_date
  • quarter_to_date
  • last_month
  • lifetime

orders

No

array of objects

The list of columns to sort by. See How to Run a Report.

format

No

enum

The format in which the report data will be returned. If this field is not specified, it will default to "csv". Possible values:

  • "csv": Comma-separated values
  • "excel": Tab-separated values
  • "html"

reporting_decimal_type

No

enum

The decimal mark used in the report. Possible values:

  • "comma"
  • "decimal" (period)
    If this field is passed, it overrides any reporting decimal preferences set at the user and member levels.

emails

No

array

The list of email addresses to which the reporting data will be sent. The reporting data is sent as an attachment, and the body of the email contains the information below.

  • Report type
  • Member, Advertiser, or Publisher name and ID
  • Run date
  • Start date
  • End date
  • Timezone
  • User who generated the report

    Report results larger than 15 MB will not be emailed. See Reporting Best Practices for ways to prevent results from being too large.

escape_fieldsnoboolean

When true, it adds quotes around each field in the report output to allow for safer import into Excel. This only applies to CSV and tab-delimited reports.

How to run a report

Step 1. Create a JSON-formatted report request

The JSON file should include the specific report_type that you want to run, as well as the columns (dimensions and metrics) and report_interval ("today", "yesterday", "month_to_date", etc.) that you want to retrieve. You can also include filters for dimensions, define granularity (year, month, day), and specify the format in which the data should be returned. The format options are:

  • "csv" - Comma-separated file
  • "excel" - tab-separated file
  • "xlsx" - modern XML-compatible Excel format (zipped)

To filter a dimension by more than one value, use an array. For example:

Correct:

"filters": [{"bid_type": ["learn","optimized"]}, {"geo_country":"US"}]

Incorrect:

"filters": [{"bid_type":"learn"}, {"bid_type":"optimized"}, {"geo_country":"US"}]

See JSON above for more details about the fields that can be included in the request. For a full list of available dimensions and metrics, see the documentation for the specific report type that you want to run, or pull that report's metadata as described in REST API for Viewing Metadata.

Step 2. POST the request to the Report Service

You POST the JSON request and get back a report ID.

Alternatively, you can get a Report ID via a POST request using a saved report ID. For more information, see the Saved Report Service:

Step 3. GET the report status from the Report Service

Make a GET call with the report ID to retrieve the status of the report. Continue making this call until the execution_status is "ready". Then use the report-download service to save the reporting data to a file. (This is described in the next step.)

Step 4. GET the report data from the Report Download Service

To download the report data to a file, make another GET call with the report ID, but this time to the report-download service. You can find the service and report ID in the url field of the previous GET response. When identifying the file that you want to save to, be sure to use the file extension of the "format" that you specified in your initial POST.

If an error occurs during download, the response header will include an HTTP error code and message. Use -i or -v in your request to expose the response header.

You can then open the file.

 Expand for example of network_analytics report

Report Data Size Limitations

Report results larger than 15 MB will not be emailed to recipients specified in the JSON request.

Reports that take longer than 15 minutes to process will timeout and return with an error status. This amount of processing time roughly corresponds to 1MM rows of data. If your reports routinely timeout, please consider one of the following options:

  • Verify that you really need all that data. If you don't, update your report requests with a shorter time interval or fewer dimensions. For tips on preventing reports from being unnecessarily large or taking too long to process, see Reporting Best Practices below.
  • If you really do need all of that data, follow the instructions in Report Pagination.

Report Throttling

In order to ensure that our systems operate as smoothly as possible for all users, the Report Service throttles report requests at both the member level and the user level. This page describes how the limits are determined, and how we handle requests that exceed the limits defined for each member and each user.

User Limits

When a report is submitted by User A, a check is performed to see if User A has submitted 5 report requests in the past 15 minutes that are in pending status or currently being processed. If so, an error is signaled.

Member Limits

A given member is limited to n report requests being processed at the same time, where n is determined by the member's contract with AppNexus. Any report requests submitted after the limit has been reached are placed in a queue. No warnings or alerts are given.

Example

User- and member-level throttling interact with each other as shown in the following example. Assume that User A and User B are associated with the same member; this member has a limit of 5 concurrent report requests. We assume for this example that the following report requests are all submitted within a 15 minute time span:

Report Request

User

Outcome

1

User A

Processing

2

User A

Processing

3

User B

Processing

4

User B

Processing

5

User B

Processing

6

User A

Enqueued

7

User A

Enqueued

8

User A

Enqueued

9

User A

Error

Report request # 6 is placed in the queue, since there are already 5 report requests being processed for this member. For the same reason, requests # 6-8 are also placed in the queue. Finally, we can see that request # 9 causes an error to be signaled, since User A has submitted their 6th report request within a 15 minute time span.

Conversion Data

Conversions (and related data) in reports are processed asynchronously. As a result, reports are available more quickly, while some conversion-related data is still being processed in the background. For more information, see Asynchronous Conversion Attribution (Customer login required).

Reporting Best Practices

Here are some tips for preventing your reports from being unnecessarily large or taking a long time to process:

  • Shorten the report_interval (e.g., from "lifetime" to "last_48_hours")
  • Add more higher-level filters (e.g., for a specific publisher, advertiser, campaign, etc.)
  • Avoid combining granular buy-side and sell-side dimensions (e.g., creative and placement), as this increases the number of rows exponentially. If you need to report on such combinations, consider using Bulk Reporting Feeds or the Log-Level Data Service.

If you must pull large reports that take a long time to process, follow the instructions in Report Pagination.

See When Reporting Data Was Last Updated

To determine when a report was last updated, use the Report Status Service.