Reporting is a powerful feature that allows you to access the rich collection of AdWords API reports. Reporting queries are specified using the AdWords Query Language, and the returned values are simple JSON objects. For example,

var report =
    "SELECT AdGroupId, Query, Ctr, Cost, Impressions " +
    "WHERE  Impressions < 10 " +

var rows = report.rows();
while (rows.hasNext()) {
    var row =;
    var query = row["Query"];
    var impressions = row["Impressions"];

Note that reports do not support the ORDER BY or LIMIT clauses. Results will be returned in no particular order.

Read the Reference for more details about the API. For an example on using reports in Google Ads scripts, see the Search Query solution.

Key benefits of using reports:

  • Access to a wide variety of stats not available to regular Google Ads entities (including segments).
  • Ability to access a large amount of data. Reports are not presently subject to any quotas, and fetching of a million-row report is possible.
  • Performance—the download of a report may take a while, but iterating through the report rows is blazingly fast.

API Versioning

As new versions of the AdWords API are released and old ones get deprecated, certain report fields, or sometimes entire reports, may disappear. This can inadvertently break your code. As a safety mechanism, consider specifying the version of the API that your code expects to work with:

var report =, {
    apiVersion: 'v201802'

This will ensure that the code won't break when a successive version is released.

As a down side, v201802 will eventually get deprecated and sunset. At that time, scripts that had specifically referenced that version will break. Use apiVersion thoughtfully.

Send feedback about...

Google Ads scripts
Google Ads scripts
Need help? Visit our support page.