Skip to end of metadata
Go to start of metadata

Report Service

The Report Service offers reporting data of interest to both buyers and sellers. It's used to answer questions such as:

  • How much money was spent?
  • How many impressions were seen?
  • How many impressions were sold?
  • How much revenue was earned?

This is a read-only service; although you will POST a JSON-formatted report request, this will not alter any data in the Imp Bus cache. Note that you must be authenticated as a "bidder" user type to run reports, and that each report type provides its own metrics, filtering, and grouping options.

Need more than 90 days of data?

The platform_buyer and platform_seller report types pull from tables that store the last 90 days worth of data. For older data, please use the bidder_pricing_report and seller_invoice_report report types.

The Report Service runs reports asynchronously, which means it can run several processes in parallel. When you make a report request, you will either receive the report, an error message, or a pending message. For more information, see How to Retrieve a Report below.

There is also a graphical user interface (UI) to view this reporting data at https://bidder.adnxs.net. If you do not have access to this UI, contact your AppNexus representative.

Note that the UI does not expose all functionality that is available via the API. It only exposes the platform_buyer analytics report. If you need a different report, you must use the API.

On This Page

Report Types

The primary report types are:

REST API for Viewing Metadata

There are two layers of data in the Report Service: metadata and actual data. Metadata is a list of available reporting parameters.

To run a custom report you will need a JSON-formatted request. You can request data by a filter, group, or column. A filter will filter out results. A having, such as day, will filter based on aggregated data. You can also search by individual parameters, such as imps_sold.

To return metadata for bidder_pricing_report type:

To return metadata for platform_buyer type:

To return metadata for seller_invoice_report type:

To return metadata for platform_seller type:

Note

You can also use a more standard query format to return metadata:

For example:


Metadata comes in the following format:

Metadata Example

 click here to expand

REST API for Data Retrieval

Request a report: 

Request the status of a report:

Retrieve report data:

JSON Fields

Field

Required

Type

Description

report_type

yes

enum

Must be one of:

  • "platform_buyer"
  • "platform_seller"
  • "bidder_pricing_report"
  • "seller_invoice_report"
  • "completed_creative_audits"
  • "bidder_bid_error_report"

This determines which information will be returned.

filters

no

array

List of filters to apply to the report. See the documentation for each individual report to see which fields can be filtered on. For a simple example, see the How to Retrieve a Report below.

The is_delivered filter value is only true if the impression was served successfully. Otherwise, it's false.

columns

yes (at least one)

array

List of columns to include in the report. See the documentation for each individual report to learn which columns are available. For a simple example, see the How to Retrieve a Report below.

row_per

no

array

List of groupings to include in the report. See the documentation for each individual report to learn which columns can be used to group by. For a simple example, see the How to Retrieve a Report below.

start_date

no

string

The ending date for the report.

  • 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 report types that do not offer hourly data, this must be formatted as "YYYY-MM-DD".

end_date

no

string

The ending date for the report.

  • 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 report types that do not offer hourly data, this must be formatted as "YYYY-MM-DD".

The end_date is non-inclusive. For example, if you start a monthly report on "2012-07-01" and end the report on "2012-07-31", your report will not include data from the last day of the month. The correct way to retrieve this data would be to end the report on "2012-08-01".

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_7_days
  • lifetime
  • month_to_date
  • mtd
  • last_month

timezone

no

string

The timezone in which the data will be reported. For a list of possible timezone values, see Reporting Timezones.

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 Retrieve 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 and define granularity (year, month, day) and specify the format in which the data should be returned. The format options are:

  • "csv" - Comma-separated file
  • "xls" - Tab-separated M.S. Excel file
  • "xlsx" - Native M.S. Excel format

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

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 https error code and message. Use -i or -v in your request to expose the response header.

You can then open the file.

 Expand for a screenshot

Schedule Recurring Reports

You can automate the reporting process by creating saved versions of the reports you care about and having our system email the data to you at specified intervals. For more information about how to set up these automated reports, see the Saved Report Service.

Related Topics