Reporting of performance data is an integral part of most AdWords API applications. With the API's flexible reporting options, you can obtain a report with performance data for an entire campaign, or focus more narrowly, for example, on the search queries that triggered your ad.
This guide describes the steps necessary to create and submit a report request to the AdWords server. It then describes some more advanced reporting concepts like data segementation, data formats, and attribution.
For a complete list of all the available report types in the AdWords API, see the Report Types reference pages.
There are two main steps to generate reports from the API:
- Create a report definition. The report definition is an XML or AWQL fragment that defines the parameters of your report, including the report name, the types of information to include in the report, the download format, and other details.
- Enclose the report definition in an HTTP POST request, and submit it to the AdWords server.
Both of these steps are described below.
Create a report definition
The report definition constitutes the body of the request, where you specify the elements to include in the report.
You can create report definitions in XML or in AWQL, the AdWords Query Language.
The sections below cover XML-based report definitions. Check out the reporting section of the AWQL guide if you'd prefer to use AWQL instead of XML.
Below is an example of an XML report definition. The table below it defines each element in the report definition.
<reportDefinition xmlns="https://adwords.google.com/api/adwords/cm/v201708"> <selector> <fields>CampaignId</fields> <fields>AdGroupId</fields> <fields>Impressions</fields> <fields>Clicks</fields> <fields>Cost</fields> <predicates> <field>AdGroupStatus</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>
SELECT CampaignId, AdGroupId, Impressions, Clicks, Cost FROM ADGROUP_PERFORMANCE_REPORT WHERE AdGroupStatus IN [ENABLED, PAUSED] DURING LAST_7_DAYS
|Report Definition Element||Description|
||This is the report definition header. Use the same URL shown in the request, ensuring the correct version of the API is listed.|
||The selector section contains a list of
You can also use the
||Predicates are equivalent to filters in the AdWords user interface. A predicate is comprised of a report field, operators, and values. Predicates are treated as inclusive (AND) conditions.|
||Indicates the type of report you are requesting. See the Reports Types pages for more information and the complete list of report types.|
||The date range your report should encompass. See Date ranges below for more information.|
||The format in which you want to download the report. See Download formats below for more information.|
XML schema definition
An XML Schema Definition (XSD) defining the structure of the
reportDefinition is published at the following URL:
are supported; for the former, you would need to URL-encode the submitted XML.
To specify the report's date range, use a
the report definition XSD.
|Valid DateRange Types||Reports are generated for...|
||The last 7 days not including today.|
||The seven-day period starting with previous Monday.|
||The 5 day business week, Monday through Friday, of the previous business week.|
||All days in the current month.|
||All days in the previous month.|
||The entire available time range.|
||A custom date range. See Custom date ranges below for more information.|
||The last 14 days not including today.|
||The last 30 days not including today.|
||The period between the previous Sunday and the current day.|
||The period between the previous Monday and the current day.|
||The seven-day period starting with the previous Sunday.|
CUSTOM_DATE, only the
dateRangeType is required.
<reportDefinition xmlns="https://adwords.google.com/api/adwords/cm/v201708"> ... <dateRangeType>LAST_7_DAYS</dateRangeType> </reportDefinition>
Custom date ranges
If you want a custom date range, then you must:
- Include a
YYYYMMDDformat on your
<reportDefinition xmlns="https://adwords.google.com/api/adwords/cm/v201708"> <selector> ... <dateRange> <min>20150201</min> <max>20150301</max> </dateRange> </selector> <dateRangeType>CUSTOM_DATE</dateRangeType> </reportDefinition>
... DURING 20150201,20150301
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, see the data freshness documentation.
Prepare the request
Once your report definition is created, you can now prepare the HTTP POST request.
You can 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.
You'll probably reach the Queries Per Second (QPS) limit (
before you exceed the number of open connections allowed on the server.
Reporting requests do not count toward the daily operations quota, but
there is a report downloads-per-day limit.
For an XML report definition, the
POST request body must contain a parameter
__rdxml" whose value is your XML report definition.
Use the normal HTTP header values when downloading reports:
||Authorization to download the report. Use the same
||Your developer token consisting of a unique string, for example, 1a2B3c4D5e_-6v7w8x9y0z.|
||Customer ID of the client account.|
You can specify the following optional HTTP headers to control whether your report includes a header or summary row:
|Optional HTTP Header||Description|
HTTP request URL
The request consists of an HTTP POST to the AdWords server at the following URL:
Here is a complete example showing the report definition above enclosed within an HTTP POST request.
POST /api/adwords/reportdownload/v201708 HTTP/1.1 Host: adwords.google.com User-Agent: curl, gzip Accept: / Accept-Encoding: gzip Authorization: Bearer [Enter OAuth 2.0 access token here] developerToken: [Enter developerToken here] clientCustomerId: [Enter clientCustomerID here] Content-Length: 784 Expect: 100-continue Content-Type: multipart/form-data; boundary=------------------------12d01fae60c7b559 Parameters: __rdxml: <?xml version="1.0" encoding="UTF-8"?> <reportDefinition xmlns="https://adwords.google.com/api/adwords/cm/v201708"> <selector> <fields>CampaignId</fields> <fields>AdGroupId</fields> <fields>Impressions</fields> <fields>Clicks</fields> <fields>Cost</fields> <predicates> <field>AdGroupStatus</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>
POST /api/adwords/reportdownload/v201708 HTTP/1.1 Host: adwords.google.com User-Agent: curl, gzip Accept: */* Accept-Encoding: gzip Authorization: Bearer [Enter OAuth 2.0 access token here] developerToken: [Enter developerToken here] clientCustomerId: [Enter clientCustomerID here] Content-Length: 182 Expect: 100-continue Content-Type: multipart/form-data; boundary=------------------------12d01fae60c7b559 Parameters: __fmt: CSV __rdquery: SELECT CampaignId, AdGroupId, Impressions, Clicks, Cost \ FROM ADGROUP_PERFORMANCE_REPORT \ WHERE AdGroupStatus IN [ENABLED, PAUSED] DURING LAST_7_DAYS
If the report request is successful, the server returns a Response Code of
A Response Code of
400 indicates an API error; check for any issues with
the XML in your report definition.
A Response Code of
500 typically indicates a temporary problem with the server;
if this error occurs, retry the request after a few moments.
Reports for multiple accounts
A given report request can only include data from a single AdWords account.
If you need to gather reporting data for multiple accounts, submit a separate
report request for each account by setting the
The report download request may time out on extremely large data sets. 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.
If you encounter timeouts or errors, try a shorter date range or use predicates to break up the report request into multiple, smaller requests. For example, instead of running a single report for all campaigns, you could submit multiple requests that each filter for a subset of Campaign IDs.
Supported download formats
|CSVFOREXCEL||The format for Excel. This uses a format of unicode which is prepended with a BOM (byte order marker) to signal to Excel that it is unicode. Excel defaults to use tab as a separator when unicode is being used. If comma is used then Excel will put all of the data in each row into a single column (by default).|
|CSV||The csv (comma separated) output format.|
|TSV||The tsv (tab separated) output format.|
|XML||The xml output format.|
|GZIPPED_CSV||The gzip compressed csv (comma separated) output format.|
|GZIPPED_XML||The gzip compressed xml output format.|
Choosing the right report
Because of the extensive reporting options available in the AdWords API, determining the correct report for a particular business need can be tricky.
Use the chart below to determine the most suitable report, then check out the details for that report on the Report Types page.
For more detailed statistics, you can split the data by segments. For example, you might be interested in knowing the number of impressions specific to the Google Search Network, separate from the Google Display Network; in which case, you will want to segment your report by network.
Segmentation, which is available in the UI as a separate menu, is achieved in
the API by just adding the proper field to the report. For example, adding the
AdNetworkType1 to an Ad Group Performance report results
in a report with a row for each ad group and network combination, and
the statistical values (impressions, clicks, conversions, etc.) split between
them. While in the UI only one segment at a time can be used for display, with
the API you can combine multiple segments in the same report. Keep in mind that
the amount of rows can increase exponentially for each additional segment field
included in your report.
Every report is segmented by its unique key. For example,
the Keywords Performance
report is implicitly segmented by
though they're not included in the selector fields, because a keyword is
identified by both
Keyword,MatchType,Impressions Keyword1,Exact,3 Keyword2,Exact,10 Keyword3,Exact,5 Keyword4,Broad,4
Single and multiple attribution
When an impression occurs on the Display network, the criteria that play a role in this occurrence can be recorded in one of two ways: single or multiple attribution.
With single attribution, only one of the triggering criteria (such as placement, age, keyword, etc.) is recorded for a given impression. An impression may be triggered by multiple criteria, but on a single attribution report the impression and all of its stats are attributed only to a single criterion.
Each impression is counted exactly once (under one criterion); adding up all the criteria will give you values that match the totals in multiple attribution reports.
The example below shows a Criteria Performance Report (single attribution) for a campaign targeting only the Display Network, and using only verticals and placements as criteria. The report shows 10 total impressions across five rows, one row for each of three placements and one row for each of two verticals that triggered impressions—each getting two impressions.
Keyword / Placement,Impressions www.example.com,2 www.example.ca,2 www.example.net,2 Computers & Electronics,2 Sports,2
With multiple attribution, up to one criterion in each dimension that triggered the impression will have the impression recorded for it. Multiple attribution reports can be thought of as criteria type-specific reports: Unlike single attribution where a row can contain different criteria types, each multiple attribution report contains criteria for only one criteria type.
For example, the Gender Performance report summarizes all of your impressions by Gender, the Age Range Performance report summarizes impressions by AgeRange, and so on. The Display Topics Performance and Placement Performance reports also follow this model.
Unlike single attribution, multiple attribution reports should NOT be aggregated together, since this may double count impressions and clicks.
Topic,Impressions Computers & Electronics,6 Sports,4 Placement,Impressions www.example.com,4 www.example.ca,3 www.example.net,3
If you target Display Only with verticals (topics) and placements, and run a Display Topics report, you'll get one row for each vertical (topic) that triggered impressions. Likewise, a Placements performance report will return one row per impressions. These reports are covering the same impressions, because up to one vertical and one placement will both be attributed to each impression.
In single attribution reports, all keywords that triggered impressions on the
display network will be represented by a special keyword (text:
Keyword ID,Impressions 23458623485,2 23655322314,2 23953456345,2 3000000,4
If you target keywords and placements for Display Only and run an Ad
Performance report, you'll get a row for each ad and triggering criteria
combination for placements, and a single row with ad and ID
accounts for all the display keywords that triggered that ad (where single
attribution chose the keyword rather than a placement).
A criteria ID of
3000004 was used for a feature that has since been removed
A criteria ID of
3000006 represents stats associated with the
Display Campaign Optimizer.
Format of various fields
While all fields returned in reports have a
Type, the actual values returned won't always match these values. You should
always check the Notes column, which often contains additional information
about the expected format of values. For example, the Notes column for
Percentage returned as "x.xx%".
Money fields in reports
Fields of type
Money are returned in micro currency units (micros) but may be
prefixed with "auto: " or may simply be the string "auto" if automatic bidding
For example, $1.23 will come back as
1230000 (1.23 x 1,000,000).
Micro amounts always refer to the account's local currency.
When filtering on money fields, you'll have to provide the value in micros.
WHERE AverageCpc > 1000000 will return rows where the
AverageCpc is greater than $1 (one unit of the account currency).
Quality score in reports
A value of two dashes (
--) are used to indicate that no current quality score
is available for a keyword. In addition, the column
HasQualityScore allows you
to easily filter for keywords that have no quality score available. For example,
the following AWQL query selects keywords that have a valid quality score:
SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, QualityScore FROM CRITERIA_PERFORMANCE_REPORT WHERE Status IN [ENABLED, PAUSED] and HasQualityScore='TRUE'
The following table summarizes the behavior for
|Has a valid quality score||Between
|Insufficient impressions or clicks to determine quality score||
|Has not served recently||
|Display keyword whose quality score could not be determined||
A value of two dashes (--) indicates there is no value for this cell.
Lists and maps
Items of a list will be formatted using JSON; for example, a
PLACEHOLDER_FEED_ITEM_REPORT value would consist of an array of strings:
["Monday, 6:00PM - 9:00PM","Tuesday, 6:00PM - 9:00PM","Wednesday,6:00PM - 9:00PM", "Thursday, 6:00PM - 9:00PM","Friday, 6:00PM - 9:00PM"]
Similarly, for a map (such as
Luxury Cruise to Marsfor a
text = 'Luxury Cruise to Mars'.
Not a parentfor a
parentType = PARENT_NOT_A_PARENT.
ageRangeType = AGE_RANGE_18_24.
However, the criteria types below are more complex and will have a string
representation of the form
To get more details for each identifier, use either of the following:
To get more details for each identifier, see the description for the
ContentLabelTypeinstance that matches the identifier (ignoring case).
To get more details for each identifier, use the
DisplayNamefield in reports.
To get more details for each identifier, use either of the following:
This section describes how to resolve some common reporting issues.
Empty default rows returned in reports
You might see reports containing rows labelled
contain blank values. These rows are typically returned when your
report selectors are not logically consistent. This could occur
if you select a sub-field of a parent category when you didn't
select the parent category in the report definition, for example,
if you specify a field such as
ConversionTypeName without also
selecting its parent
If these rows appear in your reports, checking the logical consistency of the selectors used to generate the report should reveal the source of the problem.
Selecting system-wide default conversion trackers
The AdWords user interface and the AdWords API handle system-wide default conversion trackers in special ways that allow for cleaner presentation in the user interface, and automatic translation when running reports in languages other than English.
Using a system-wide default conversion tracker as a selector
in a report definition without specifying its
id can produce
unexpected results in reports.
For example, if you use the
system-wide default conversion tracker, and specify its
the row is rendered in AdWords user interface reports as Store Visits.
If you specify the same
id in a report definition through the API, it also
recognizes the selection as a system-wide type, and renders it as
Store Visits. Moreover, if you run the report in another language, this
phrase is automatically translated, since the
system understands you've explicitly selected this system-wide default
System-wide default conversion trackers are user-modifiable, and the
system retains any changes you make to them. Therefore, if you don't
explicitly select the
id, the report returns
the default name
store_visits, since it can't determine if
you intended to include the
id of the system-wide default conversion tracker,
or a user-defined
Thus, when using system-wide default conversion trackers in your reports,
be sure to explicitly specify the
id of the conversion tracker to ensure