Reporting Best Practices

Stay organized with collections Save and categorize content based on your preferences.

Build new reports in the UI first

Reports are subject to a number of restrictions and requirements pertaining to reporting types, filters, dimensions, and metrics. These limitations are enforced in the API, returning an HTTP 400 error. In order to avoid errors when building reports, we recommend that you first build new reports in the Display & Video 360 UI.

After building your report, click the "Try this API" feature on the reference docs page to perform a queries.get of the Query resource. You can use the returned JSON to build future reports.

Save and re-use reports

We recommend that you create and save reports for queries you run regularly because inserting and deleting the same report multiple times wastes resources. Using the set Range values, such as PREVIOUS_DAY or LAST_7_DAYS, in the dataRange field makes reports more reusable.

Schedule reports

Ad hoc or one-off reports can be wasteful of resources because they are run individually and may execute against an incomplete dataset. Scheduled reports make the best use of reporting resources because they are run in bulk and are guaranteed not to execute until the previous day's data has completed processing. See the available scheduling fields for details.

Combine similar reports

If you regularly generate reports with identical metrics and date ranges for different advertisers or partners, we recommend that you combine the reports to optimize their report volume.

You can combine similar reports by appending the filters of all of the reports and adding all filter types as dimensions. After generation, you can split the rows of the resulting report along the original filter values to produce the original reports.

Consider reporting quotas

Responsible use of the Display & Video 360 reporting feature is enforced through the following product-wide usage quotas.

Ad-hoc report executions per day

Limits the number of ad-hoc reports a user can run in a 24-hour period. To stay under this quota:

Active scheduled reports

Limits the number of reports a user can have actively scheduled at a given time. To stay under this quota:

Concurrent reports

Limits the number of reports a user can run simultaneously. To stay under this quota:

  • Schedule reports that run regularly.
  • Deactivate unnecessary API scripts.
  • Track when your reports are done by polling using exponential backoff logic.

If you have optimized your reporting implementation and you still find yourself exceeding your given quota, contact Display & Video 360 support using the contact form.

Use exponential backoff when polling for report status

It's not possible to predict how long a report will take to run. The length of time can range from seconds to hours depending on many factors including date range and the amount of data to be processed, for instance. There's also no correlation between report run-time and the number of rows returned in the report. You therefore need to regularly retrieve the report resource using queries.reports.get method and check if the resource's metadata.status.state field has been updated to DONE or FAILED to determine whether it has finished running. This is a process known as "polling".

While polling is necessary, an inefficient implementation may quickly exhaust your quota when encountering a long running report. Thus we recommend that you use exponential backoff to limit retries and conserve quota.

Exponential backoff

Exponential backoff is a standard error handling strategy for network applications in which the client periodically retries request over an increasing amount of time. Used properly, exponential backoff increases the efficiency of bandwidth usage, reduces the number of requests required to get a successful response, and maximizes the throughput of requests in concurrent environments.

The flow for implementing simple exponential backoff is as follows:

  1. Make a queries.reports.get request to the API.
  2. Retrieve the report object. If the metadata.status.state field is not DONE or FAILED, that indicates that the report is not finished running should continue polling.
  3. Wait 5 seconds + a random number of milliseconds and retry the request.
  4. Retrieve the report object. If the metadata.status.state field is not DONE or FAILED, that indicates that the report is not finished running should continue polling.
  5. Wait 10 seconds + a random number of milliseconds and retry the request.
  6. Retrieve the report object. If the metadata.status.state field is not DONE or FAILED, that indicates that the report is not finished running should continue polling.
  7. Wait 20 seconds + a random number of milliseconds and retry the request.
  8. Retrieve the report object. If the metadata.status.state field is not DONE or FAILED, that indicates that the report is not finished running should continue polling.
  9. Wait 40 seconds + a random number of milliseconds and retry the request.
  10. Retrieve the report object. If the metadata.status.state field is not DONE or FAILED, that indicates that the report is not finished running should continue polling.
  11. Wait 80 seconds + a random number of milliseconds and retry the request.
  12. Continue this pattern until the report object is updated or a maximum time elapsed is reached.

If the report finishes running and ends in a DONE state, then you can retrieve the generated report file from Google Cloud Storage at the path given in the metadata.googleCloudStoragePath field.