Reporting

Ad Exchange provides the following reports:

  • The CSV performance report provides information on the performance of your bidder application.
  • The Snippet status report provides information on whether a creative has been approved and helps debug serving problems.

You can also get performance reports through the Performance report API.

CSV performance report

The CSV Performance Report contains information that helps you to understand the performance of your bidder application. The report is generated hourly and is made available via Google Cloud Storage. The data in the report is grouped by Trading Location.

Trading location

The report is in CSV format where the left-most column provides a POSIX timestamp followed by the name of the trading location as listed below. Some columns provide a value for each minute covered by the report. A report overlaps the previous report so there are always more than 60 values for these columns. Other columns have just one value if the value represents a maximum over the whole report time period. Zero values are provided when there is no data for the column for the given time and region.

  • The possible values of <Trading location> are:
    • US_WEST
    • US_EAST
    • EUROPE
    • ASIA

    The report contains data for all trading locations even if your bidder application is not configured to receive traffic from all locations.

  • With each row in the report including data applicable to the trading location listed in column 2, the following datapoints are included, each in its own column headed by the type name:
    • max(eligible-requests): the maximum number of queries per second (QPS) that matched your pretargeting criteria in the region over the time covered by the report.

    • requests-sent: the average number of QPS sent to your bidder application for each minute covered by the report.

    • successful-responses: the average number of QPS that had a successful response for each minute covered by the report. A successful response is a response that arrives on time, has a 200 OK HTTP response code, and contains a BidResponse protocol buffer that can be parsed correctly. Note that a successful response need not return ads.

    • successful-responses-with-ads: the average number of QPS that had a successful response that contained at least one ad for each minute covered by the report.

    • requests-timeout: the average number of QPS that timed out for each minute covered by the report. A timed out request is a request for which a response is not received within 100ms.

    • no-content-responses: the average number of QPS for which the response contained no content for each minute covered by the report. A no content response is a response that has a 200 OK HTTP response code but 0-length data. Note that this is considered an error, as a 'no bid' response should contain a BidResponse protocol buffer with no ad messages.

    • unparseable-responses: the average number of QPS for which the response could not be parsed for each minute covered by the report. An unparseable response is a response that contains data that can not be parsed correctly into a BidResponse protocol buffer.

    • 50th-percentile-latency, 85th-percentile-latency, 95th-percentile-latency: this is the Nth percentile round trip latency as perceived from Google servers for each minute covered by the report. Note that this is a weighted average among all Google data centers that are sending you traffic in a particular region, weighted by the amount of traffic per data center.

The report consists of three files:

  • csv-field-descriptions.txt contains descriptions of the CSV fields.
  • rtb-report-<timestamp>-trading-location.csv contains CSV data ordered by the newest first.
  • rtb-report-<timestamp>-trading-location-incr.csv contains CSV data ordered by the oldest first.

Please contact your technical account manager to enable this feature for your account.

Snippet status report

The Snippet Status Report contains the approval status of your creatives, as well as the sensitive and product categorization that the Ad Exchange automatically detects. There are two versions of this report: a human readable text format and a binary protocol buffer format. You can use this report to determine whether a creative has been approved, and to help debug serving problems. Both versions of the report are provided via Google Cloud Storage.

This report is available via HTTP. The payload of the HTTP response is gzip-compressed according to RFC 1952. To uncompress the file from the command line, run gzip -d <filename>. To uncompress the file programmatically, you can use zlib, or a similar compression library, that supports the gzip format. The result is either a text file or a serialized protocol buffer, depending on the report version you download. The protocol buffer version's encoding is similar to the payload of the POST request in a BidRequest, and can be parsed using the following snippet.

string compressed = /* the payload from the GET request */;
string uncompressed = gunzip(compressed);
SnippetStatusReport snippet_report;
if (snippet_report.ParseFromString(uncompressed)) {
  // Process the snippet report.
}

The Snippet Status Report also lists the top reasons why a creative is filtered. For more details, see the comments of the SnippetFiltering message in the snippet-status-report.proto file.

The protocol buffer definition for SnippetStatusReport is available on the reference data page.

Each entry in the snippet status report contains a buyer_creative_id that you have set in your bid response. You can use this field to correlate snippet status information with your creatives. Each snippet will have a status of NOT_CHECKED, APPROVED or DISAPPROVED. If the Ad Exchange has classified the creative, the snippet status item will have the product and sensitive categories we have associated with the creative, as well as an advertiser id if one is available.

Please contact your technical account manager to enable this feature for your account.

You can use the Snippet Status Report Generator to generate Snippet Status Reports.

Performance report API

You can get performance reports by calling performancereport. When calling the API, you must provide a reporting period (start time and end time) and your account ID. You can also provide a pagination token and a value indicating the maximum results in the report. For example, the following call:

performancereport?endDateTime=2013-06-13T17:25:00Z&startDateTime=2013-06-13T17:20:00Z&accountId=44773513

returns the following performance report:

{
 "kind": "adexchangebuyer#performanceReportList",
 "performance_report": [
  {
   "kind": "adexchangebuyer#performanceReport",
   "timestamp": "1371835200",
   "region": "EUROPE",
   "latency50thPercentile": 0.03306867574006745,
   "latency85thPercentile": 0.033068675740067444
  },
  {
   "kind": "adexchangebuyer#performanceReport",
   "timestamp": "1371835200",
   "region": "US_EAST",
   "latency50thPercentile": 0.031355335926353825,
   "latency85thPercentile": 0.01820351400729759
  },
  {
   "kind": "adexchangebuyer#performanceReport",
   "timestamp": "1371835200",
   "region": "ASIA",
   "latency50thPercentile": 0.029531352482377874,
   "latency85thPercentile": 0.029335240957323264
  },
  {
   "kind": "adexchangebuyer#performanceReport",
   "timestamp": "1371835200",
   "region": "US_WEST",
   "latency50thPercentile": 0.027170472757130575,
   "latency85thPercentile": 0.027170472757130575
  }
 ]
}

FAQ

I have more than 1000 reports in my bucket, and the Cloud Storage API call for listing objects in a bucket returns at most 1000 entries. What do I do?
The Cloud Storage documentation for this API call provides two ways to handle this use case:
  1. The API supports pagination by returning along with the truncated responses a nextMarker parameter which you can use to indicate the starting point in the next request (with marker). This in effect allows you to "page" through the entire bucket.
  2. The API supports listing only the objects that have a specific prefix. Given the RTB reports file naming scheme, one can, for example, list only objects for a specific month—which should be well under the limit. For example, specifying prefix=<bucket name>/csv_report/rtb-report-201206 will fetch all objects for June 2012.

Send feedback about...

Real-Time Bidding Protocol
Real-Time Bidding Protocol