Digital Platform API - Report service

Article
03/04/2024

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.

Note

For more information about how to sync Xandr 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.

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 Xandr.	Lifetime - some data at reduced granularity after 100 days.
Buying Billing Report `buyer_invoice_report`	Network	Reporting for financial reconciliation with buying related charges.	1095 days
Selling Billing Report `seller_invoice_report`	Network	Reporting for financial reconciliation with selling related charges.	1095 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`	Network	Video event reporting across advertisers and publishers.	420 days
Network Advertiser Video Analytics `video_analytics_network_advertiser`	Network	Video event reporting for a single advertiser.	420 days
Network Publisher Video Analytics `video_analytics_network_publisher`	Network	Video event reporting for a single publisher.	420 days
Buyer Segment Performance Report `buyer_segment_performance`	Network	Reporting on segment performance across campaigns and multiple advertisers.	45 days
Seller Brand Review Report `seller_brand_review`	Network	Reporting on brand performance across all of network's inventory.	428 days
Publisher Brand Review Report `publisher_brand_review`	Publisher	Reporting on brand performance across all of publisher's inventory.	428 days
Network Creative Frequency & Recency `network_advertiser_frequency_recency`	Network	Network reporting on creative frequency and recency for a single advertiser.	120 days
Advertiser Creative Frequency & Recency `advertiser_frequency_recency`	Network, Advertiser	Reporting for what an advertiser should see about its creative frequency and recency.	120 days
Network Site Domain Performance `network_site_domain_performance`	Network	Network reporting on domain performance across advertisers.	45 days
Site Domain Performance Report `site_domain_performance`	Network, Advertiser	Reporting on domain performance for a single advertiser.	45 days
Seller Site Domain `seller_site_domain`	Network	Reporting on what inventory is coming through a publisher.	60 days
Segment Loads Report `segment_load`	Network	Network reporting on segments.	30 days
Advertiser Attributed Conversions `attributed_conversions`	Network	Network reporting on advertisers' attributed conversions.	90 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.	46 days
Network Device Analytics `network_device_analytics`	Network	Report on buy-side and sell-side performance data based on devices where impressions were served.	428 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`	Network	Network report designed to give you insight into how your creatives are moving through the audit process	365 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`	Network	Network report that gives 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
Vendor Usage Report `buyer_vendor_usage_analytics`	Network	Network report that provides the details on your usage of data or platform powered by third party vendors (e.g., user segment providers), the costs of that data or feature usage , and the line items/campaigns where vendor costs were applicable.	60 days
Buyer Engagement Report `buyer_engagement_report`	Advertiser	Provides insight into the viewable duration of your display and video creatives.	Last five weeks
Buyer Deal Metrics `buyer_deal_metrics`	Advertiser, Network	Key information about deal metrics, performance, and rejection reasons that is relevant to buyers.	30 days
Seller Deal Metrics `seller_deal_metrics`	Publisher, Network	Key information about deal metrics, performance, and rejection reasons that is relevant to sellers.	30 days
Multi-Buyer Seller Deal Metrics `multi_buyer_seller_deal_metrics`	Publisher, Network	Key information about deal metrics, performance, and rejection reasons that is relevant to seller.	30 days
Key Value Analytics `key_value_analytics`	Network	Network reporting on information associated with your network's defined targeting keys and values. Impressions with key/value targeting will serve and be reported only for those impressions that were logged by a placement tag containing the kw_ prefix on the key name.	428 days
Curator Analytics Report `curator_analytics`	Curator	Provides curators insight into how money is flowing from demand to supply within their curated marketplace.	14 months
Curator Segment Performance Report `curator_segment_performance`	Curator	Provides curators insights into how their targeted segments are contributing to the overall performance of their curated deals.	14 months
Buyer Reach And Frequency Report `buyer_approximate_unique_users_hourly`	Network	Provides the information associated with "reach" which is the number of unique devices or persons exposed to ads and "frequency" which is the average number of times each unique device or person was exposed to advertisements.	90 days
Offline Attribution Report `offline_attribution`	Advertiser	Provides insight into your line item's performance in influencing in-store purchases among your target audiences. The Offline Attribution report is only accessible to clients who have Offline Sales Attribution enabled for their line items.	120 days
Seller CMP Analytics Report `cmp_analytics`	Network	Provides insight into the number, validity, and content of the IAB Transparency & Consent Framework (IAB TCF) strings on seller ad requests to our endpoints.	30 days
Prebid Server Premium Seller Analytics Report `prebid_server_analytics`	Network	The Prebid Server Premium Seller Analytics Report contains performance information on configured Prebid Server Premium (PSP) demand partners. Use for final delivery and performance.	30 days
Prebid Server Premium Health Analytics Report `psp_health_analytics`	Network	Data related to Prebid Server Premium bid requests and transactions. Useful for troubleshooting and optimization. Report is based on sample data multiplied to estimate the full volume of PSP activity. Use Prebid Server Premium Analytics Report and other Microsoft Monetize reports for those purposes.	99 days
Inventory Availability Report `platform_inventory_availability`	Advertiser, Publisher	Inventory availability reports offer insight into the types of inventory available on the platform.	30 days

REST API for viewing metadata

HTTP Method	Endpoint	Description
`GET`	https://api.appnexus.com/report?meta	Return meta data for all reports.
`GET`	https://api.appnexus.com/report?meta=REPORT_TYPE	Return meta data for a particular report type.

JSON fields for viewing metadata

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

Note

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.

Meta data response example (using the `network_analytics` report)

$ curl -b cookies -c cookies 'https://api.appnexus.com/report?meta=network_analytics'

{
    "response": {
        "status": "OK",
        "meta": {
            "time_granularity": "hourly",
            "columns": [
                {
                    "column": "month",
                    "type": "date"
                },
                {
                    "column": "day",
                    "type": "date"
                },
                {
                    "column": "hour",
                    "type": "date"
                },
                {
                    "column": "buyer_member_id",
                    "type": "int"
                },
                {
                    "column": "seller_member_id",
                    "type": "int"
                },
                {
                    "column": "seller_member_name",
                    "type": "string"
                },
                {
                    "column": "seller_member",
                    "type": "string"
                },
                {
                    "column": "advertiser_id",
                    "type": "int"
                },
                ...
            ],
            "filters": [
                {
                    "column": "hour",
                    "type": "date"
                },
                {
                    "column": "day",
                    "type": "date"
                },
                {
                    "column": "month",
                    "type": "date"
                },
                {
                    "column": "buyer_member_id",
                    "type": "int"
                },
                {
                    "column": "seller_member_id",
                    "type": "int"
                },
                ...
            ],
            "havings": [
                {
                    "column": "imps"
                },
                {
                    "column": "clicks"
                },
                {
                    "column": "cost"
                },
                {
                    "column": "revenue"
                },
                {
                    "column": "booked_revenue"
                },
                {
                    "column": "reseller_revenue"
                },
                {
                    "column": "profit"
                },
                ...
            ],
            "time_intervals": [
                "current_hour",
                "last_hour",
                "last_48_hours",
                "today",
                "yesterday",
                "last_7_days",
                "month_to_date",
                "quarter_to_date",
                "last_month",
                "lifetime",
                "mtd"
            ]
        }
    }
}

REST API for data retrieval

HTTP Method	Endpoint	Description
`POST`	https://api.appnexus.com/report (report JSON)	Request a report.
`GET`	https://api.appnexus.com/report?id=REPORT_ID	Request the status of a report.
`GET`	https://api.appnexus.com/report-download?id=REPORT_ID	Retrieve report data.

Note

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 for data retrieval

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"` - `"prebid_server_analytics"` - `"psp_health_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. Note: 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 section 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 Create a JSON-formatted report request below. At least one column must be specified.
`row_per` OR `groups`	No	array	Note: 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"`. Note: `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. Note: 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` - `30_days`
`orders`	No	array of objects	The list of columns to sort by. See How to run a report below.
`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. Note: Report results larger than 15 MB will not be emailed. For ways to prevent results from being too large, see Reporting Best Practices.
`escape_fields`	no	boolean	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.

`group_filters` example

{
"group_filters": [
{
"imps": {
"value": 10000,
"operator": ">="
}
}
]
}

How to run a report?

Step 1. Create a JSON-formatted report request
Step 2. POST the request to the Report Service
Step 3. GET the report status from the Report Service
Step 4. GET the report data from the Report Download Service

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)

Note

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"}]

For more details about the fields that can be included in the request, see JSON fields above. 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.

$ cat report_request

{
    "report": {
        "report_type": "network_analytics",
        "report_interval": "last_48_hours",
        "columns": ["day","imps","clicks"],
        "filters": [{"geo_country":"US"}],
        "orders": [{"order_by":"day", "direction":"ASC"},{"order_by":"imps", "direction":"DESC"}],
        "format": "csv"
    }
}

Step 2: `POST` the request to the Report service

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

$ curl -b cookies -c cookies -X POST -d @report_request 'https://api.appnexus.com/report'

{
    "response": {
        "status": "OK",
        "report_id": "ca9955709eade9a0e89f5cda5345c12r"
    }
}

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

curl -c cookies -b cookies -X POST 'https://api.appnexus.com/report?saved_report_id=30'

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

$ curl -b cookies -c cookies 'https://api.appnexus.com/report?id=ca9955709eade9a0e89f5cda5345c12r'

{
    "response": {
        "status": "OK",
        "report": {
            "name": null,
            "created_on": "2017-03-13 18:15:48",
            "cache_hit": false,
            "fact_cache_hit": false,
            "json_request": "{\"report\":{\"report_type\":\"network_analytics\",\"report_interval\":
                \"last_48_hours\",\"columns\":[\"day\",\"imps\",\"clicks\"],\"filters\":[{\"geo_country\":
                \"US\"},{\"entity_member_id\":\"514\"},{\"entity_member_id\":null}],\"orders\":
                [{\"order_by\":\"day\",\"direction\":\"ASC\"},{\"order_by\":\"imps\",\"direction\":
                \"DESC\"}]}}",
            "header_info": "Report type:,network_analytics\r\n,\r\nRun at:,2017-03-13 18:15:48\r\nStart date:,
                \r\nEnd date:,\r\nTimezone:,\r\nUser:,John Smith (9385)\r\n",
            "report_size": "10",
            "row_count": "35",
            "url": "report-download?id=ca9955709eade9a0e89f5cda5345c12r"
        },
        "execution_status": "ready"
    }
}

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.

Note

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.

curl -i -b cookies -c cookies 'https://api.appnexus.com/report-download?id=ca9955709eade9a0e89f5cda5345c12r' > /tmp/network_analytics.csv

You can then open the csv file using Microsoft Excel or similar software.

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, 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 (This is specified internally by the max_concurrent_reports_processing field on the api.member table.) 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" on the Availability of Reporting Data page.

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 (LLD) Feeds.

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

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

Share via

Digital Platform API - Report service

Report types

REST API for viewing metadata

JSON fields for viewing metadata

Meta data response example (using the `network_analytics` report)

REST API for data retrieval

JSON fields for data retrieval

`group_filters` example

How to run a report?

Step 1: Create a JSON-formatted report request

Step 2: `POST` the request to the Report service

Step 3: `GET` the report status from the Report service

Step 4: `GET` the report data from the Report Download service

Report data size limitations

Report throttling

User limits

Member limits

Example

Conversion data

Reporting best practices

Additional resources

Share via

Digital Platform API - Report service

Report types

REST API for viewing metadata

JSON fields for viewing metadata

Meta data response example (using the network_analytics report)

REST API for data retrieval

JSON fields for data retrieval

group_filters example

How to run a report?

Step 1: Create a JSON-formatted report request

Step 2: POST the request to the Report service

Step 3: GET the report status from the Report service

Step 4: GET the report data from the Report Download service

Report data size limitations

Report throttling

User limits

Member limits

Example

Conversion data

Reporting best practices

Additional resources

Meta data response example (using the `network_analytics` report)

`group_filters` example

Step 2: `POST` the request to the Report service

Step 3: `GET` the report status from the Report service

Step 4: `GET` the report data from the Report Download service