Reporting of performance data is an integral part of most AdWords API applications.

You can obtain a report with the performance data for an entire campaign. Or you can focus more narrowly, for example on the search queries which triggered your ad. See the documentation about report types to learn what options are available.

To obtain a report, your application uses AdHoc Reports to tell the API who you are, what type of report you want, your choice of download format, the name you want to give the report, and a few other things. All of this goes into the Report Definition, which your application sends to Google to initiate the download of a report.

Some statistics that go into your reports may be calculated continuously, while others may be calculated once a day. This is one aspect of how data freshness works in AdWords. To use reporting effectively, read the data freshness documentation.

If you developed an application using the now-deprecated ReportsDefinitionService, we encourage you to update your application to use AdHoc Reports. In the meantime, you can refer to archived documentation for ReportsDefinitionService.

AdHoc Reports

This method allows you to make plain synchronous HTTP requests directly to the AdWords server, an approach whose low overhead makes it suitable for high-volume reporting, especially when implemented using multiple threads (we recommend starting with 10). The HTTP request is synchronous because the call effectively blocks until the report data is ready to download.

Using AdHoc Reports, you'll probably reach the Queries Per Second (QPS) limit (RateExceededError) before you exceed the number of open connections allowed on the server.

HTTP Request

The request consists of an HTTP POST to the AdWords server at the following URL:

https://adwords.google.com/api/adwords/reportdownload/v201306

Use the normal HTTP Header values as when downloading reports:

The POST request body should contain a parameter named "__rdxml" whose value is an XML fragment that defines the report, for example:

<reportDefinition xmlns="https://adwords.google.com/api/adwords/cm/v201306">
  <selector>
    <fields>CampaignId</fields>
    <fields>Id</fields>
    <fields>Impressions</fields>
    <fields>Clicks</fields>
    <fields>Cost</fields>
    <predicates>
      <field>Status</field>
      <operator>IN</operator>
      <values>ENABLED</values>
      <values>PAUSED</values>
    </predicates>
  </selector>
  <reportName>Custom Adgroup Performance Report</reportName>
  <reportType>ADGROUP_PERFORMANCE_REPORT</reportType>
  <dateRangeType>LAST_7_DAYS</dateRangeType>
  <downloadFormat>CSV</downloadFormat>
</reportDefinition>

An XML Schema (XSD) defining the structure of the reportDefinition is published at the following URL:

https://adwords.google.com/api/adwords/reportdownload/v201306/reportDefinition.xsd

Both application/x-www-form-urlencoded and multipart/form-data Content-Types are supported; for the former, you would need to URL-encode the submitted XML.

The report download request will time out after ten minutes of idle time (no data transmitted) or one hour total elapsed time. There is no explicit data size limit; however, due to a variety of factors, the server may return an error if the report is too large.

We have provided some sample Java code that makes use of AdHoc reporting for multiple clients.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.