Find and Run Reports

Once you've identified or created a report that satisfies your needs, it's time to generate output. Report output is stored in report files, which can be retrieved and manipulated programmatically. A report file is produced as the result of running a report.

This guide details how to programmatically generate report files via the Reports service.

Find a report

In order to run a report, you need to know the report's ID. If you've just created or updated a report, this value can be found in the id field of the report resource that was returned. It's recommended that users store these returned IDs for later lookup.

If you don't know the ID of the report you'd like to run, you can look through the list of all available reports to find the one you want. The example below illustrates how to look up a report by some user-defined criteria:


Report target = null;
ReportList reports;
String nextPageToken = null;

do {
  // Create and execute the reports list request.
  reports = reporting.reports().list(profileId).setPageToken(nextPageToken).execute();

  for (Report report : reports.getItems()) {
    if (isTargetReport(report)) {
      target = report;

  // Update the next page token.
  nextPageToken = reports.getNextPageToken();
} while (!reports.getItems().isEmpty() && !Strings.isNullOrEmpty(nextPageToken));

Refer to the reference documentation for optional parameters you can specify to control how the list of returned reports are sorted and ordered. Controlling the sorting and ordering of this list can be especially useful to find reports that were modified recently.

Run a report

Once you've found a suitable report, you can use the Report service to run it and generate a new report file. Reports can be run either synchronously or asynchronously (default), depending on the complexity of the report and the time it will take to process. See the Synchronous Reports guide for details on synchronous vs. asynchronous reporting.

To run a report, you make a call to the run method of the Report service, as in the example below:


// Run the report.
File file = reporting.reports().run(profileId, reportId).execute();

The response to this request is a Files resource. If this were a successful synchronous run request, all fields of the returned resource would be filled out and the file would be ready to download. Since this was an asynchronous run request, however, certain key fields will be missing and the file's status will be set to PROCESSING, since the report has not yet finished running.

When is a report finished running?

When you run a report asynchronously, a placeholder file is generated immediately and the report is put into a queue to be processed. The placeholder will contain two key pieces of information to help you determine when the report is finished running:

  1. An id field, which can be used to reference this file in subsequent requests.
  2. A status field, which represents the current state of the report run.

To determine when a report has finished running, you'll need to periodically check the status of the file, as in the example below:


BackOff backOff =
    new ExponentialBackOff.Builder()
        .setInitialIntervalMillis(10 * 1000) // 10 second initial retry
        .setMaxIntervalMillis(10 * 60 * 1000) // 10 minute maximum retry
        .setMaxElapsedTimeMillis(60 * 60 * 1000) // 1 hour total retry

do {
  File file = reporting.files().get(reportId, fileId).execute();

  if ("REPORT_AVAILABLE".equals(file.getStatus())) {
    // File has finished processing.
    System.out.printf("File status is %s, ready to download.%n", file.getStatus());
    return file;
  } else if (!"PROCESSING".equals(file.getStatus())) {
    // File failed to process.
    System.out.printf("File status is %s, processing failed.", file.getStatus());
    return null;

  // The file hasn't finished processing yet, wait before checking again.
  long retryInterval = backOff.nextBackOffMillis();
  if (retryInterval == BackOff.STOP) {
    System.out.println("File processing deadline exceeded.%n");
    return null;

  System.out.printf("File status is %s, sleeping for %dms.%n", file.getStatus(), retryInterval);
} while (true);

When the status changes to REPORT_AVAILABLE, the file is ready to download. As shown in the above example, it is strongly recommended that you implement an exponential backoff strategy when polling like this, to optimize your request quota usage.

Send feedback about...

DoubleClick Campaign Manager
DoubleClick Campaign Manager