Incremental Reports

The new Search Ads 360 Reporting API is now available. The new API provides enhanced flexibility to build custom reports and integrate the data into your reporting applications and processes. Learn more about migrating to and using the new Search Ads 360 Reporting API.

Instead of receiving a dump of all data every time you request a report, you can periodically request only the data that has changed since your last report. These incremental reports will likely be significantly smaller than a full report.

If you request incremental reports, you should be aware of the following:

  • It's still a good idea to request a full report every once in a while, just in case some incremental changes are lost. For example, if you request weekly incremental reports during January, at the end of February you should request a full report for January to make sure you get all of the January data.
  • Since it isn't always possible to determine if some entities have changed, an incremental report will contain an entity if Search Ads 360 even suspects that the entity has changed. This means that incremental reports might contain data that hasn't changed.

To request an incremental report, specify one of the following Reports.request.timeRange properties:

changedMetricsSinceTimestamp=timestamp

Requests metrics that have changed since the specified timestamp. Because metrics are stored at a daily granularity and might change for one day but not another, such requests must be segmented by day (the date column must be present). For example, a keyword report with the columns clicks, actions, and date, would return a row for each keyword and date in which the recorded number of clicks or actions has changed since the given timestamp.

The timestamp must be no earlier than 8 days before the time of request. To capture all of the changing metrics, be sure to make a changedMetricsSinceTimestamp request at least once every 7 days, and make a full report for each date once the metrics have settled (it is safer to wait at least 7 days). An example pattern is to create two reports every day: an incremental report for metrics that have changed in the last 36 hours, and a full report for metrics that occurred 8 days ago.

changedAttributesSinceTimestamp=timestamp

Requests attributes that have changed since the given timestamp. A changedAttributesSinceTimestamp request can only include attribute columns (no metric or segment columns), and does not work for raw event reports such as conversion reports. For example, a campaign report with the columns dailyBudget and campaignStartDate would return a row for each campaign whose daily budget or start date has changed since the given timestamp.

Note that changes to parent attributes are not captured in changedAttributesSinceTimestamp reports. For example a keyword may inherit its bid strategy from the parent ad group. Even if the ad group is assigned a new bid strategy, this keyword might not appear in the report. Attribute columns whose value depends on parent entities (and therefore could change without getting picked up by changedAttributesSinceTimestamp reports) usually have the prefix "effective", such as effectiveLabelIds or effectiveBidStartegy.