To produce performance data for your agency account, run a report to initiate
an asynchronous operation for an existing
[`Report`](https://developers.google.com/authorized-buyers/agencies-and-brands/apis/agenciesandbrands/reference/rest/v1/agencies.reports#resource:-report)
template.

This guide covers how you can produce a report describing your agency
account's performance by using the Agencies \& Brands API to [run](https://developers.google.com/authorized-buyers/agencies-and-brands/apis/guides/agenciesandbrands/reports/run#run_report)
a `Report` template.

## Before you begin

Before you continue, you must complete the following:

- [Set up authentication](https://developers.google.com/authorized-buyers/agencies-and-brands/get-started/start#set_up_authentication).
- [Create a report](https://developers.google.com/authorized-buyers/agencies-and-brands/apis/guides/agenciesandbrands/reports/create-modify#create_report).

## Initiate a report run

To run an existing report, use the
[`agencies.reports.run`](https://developers.google.com/authorized-buyers/agencies-and-brands/apis/agenciesandbrands/reference/rest/v1/agencies.reports/run)
method.

The following example makes a `POST` request to initiate a report run:

### REST

#### Request

    curl --request POST \
      'https://agenciesandbrands.googleapis.com/v1/agencies/ACCOUNT_ID/reports/123456789:run' \
      --header 'Authorization: Bearer ACCESS_TOKEN' \
      --header 'Accept: application/json' \
      --header 'Content-Type: application/json' \
      --data '{}' \
      --compressed

Replace the following:

- `ACCOUNT_ID`: your account ID.
- `ACCESS_TOKEN`: your access token.

#### Response

    {
      "name": "agencies/ACCOUNT_ID/reports/123456789/operations/10486370264",
      "done": false,
      "metadata": {
        "@type": "type.googleapis.com/google.ads.agenciesandbrands.v1.RunReportMetadata"
      }
    }

### Java

```java
/*
 * Copyright (c) 2026 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
 * in compliance with the License. You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License
 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
 * or implied. See the License for the specific language governing permissions and limitations under
 * the License.
 */

package com.google.api.services.samples.agenciesandbrands.v1.agencies.reports;

import com.google.api.services.agenciesandbrands.v1.AgenciesAndBrands;
import com.google.api.services.agenciesandbrands.v1.model.Operation;
import com.google.api.services.agenciesandbrands.v1.model.RunReportRequest;
import com.google.api.services.samples.agenciesandbrands.v1.Utils;
import java.io.IOException;
import java.security.GeneralSecurityException;
import net.sourceforge.argparse4j.ArgumentParsers;
import net.sourceforge.argparse4j.inf.ArgumentParser;
import net.sourceforge.argparse4j.inf.ArgumentParserException;
import net.sourceforge.argparse4j.inf.Namespace;

public class RunReport {

  /**
   * Executes the run operation for a report.
   *
   * @param agenciesAndBrandsClient the initialized Agencies & Brands API client.
   * @param accountId the account ID of the agency that created the report.
   * @param reportId the resource ID of the report to run.
   * @throws IOException if the API returns an error.
   */
  public static void execute(
      AgenciesAndBrands agenciesAndBrandsClient, Long accountId, String reportId)
      throws IOException {
    String name = String.format("agencies/%s/reports/%s", accountId, reportId);

    System.out.printf("Running report with name \"%s\".%n", name);

    RunReportRequest requestBody = new RunReportRequest();

    // Run the specified report to start an asynchronous operation.
    Operation operation =
        agenciesAndBrandsClient
            .agencies()
            .reports()
            .run(name, requestBody)
            .execute();

    System.out.println("Successfully initiated report run operation:");
    Utils.jsonPrettyPrint(operation);
  }

  /**
   * Creates and configures the ArgumentParser for this sample.
   *
   * @return the configured ArgumentParser.
   */
  private static ArgumentParser createArgumentParser() {
    ArgumentParser parser =
        ArgumentParsers.newFor("RunReport")
            .build()
            .defaultHelp(true)
            .description("Runs a specified report asynchronously, returning an Operation " +
                "that can be used to track its progress.");

    // Required arguments.
    parser
        .addArgument("-a", "--account_id")
        .help("The account ID of the agency that created the report.")
        .required(true)
        .type(Long.class);
    parser
        .addArgument("-r", "--report_id")
        .help("The resource ID of the report to run.")
        .required(true);

    return parser;
  }

  public static void main(String[] args) {
    ArgumentParser parser = createArgumentParser();

    Namespace parsedArgs = null;
    try {
      parsedArgs = parser.parseArgs(args);
    } catch (ArgumentParserException ex) {
      parser.handleError(ex);
      System.exit(1);
    }

    AgenciesAndBrands client = null;
    try {
      client = Utils.getAgenciesAndBrandsClient();
    } catch (IOException ex) {
      System.out.printf("Unable to create Agencies & Brands API service:%n%s", ex);
      System.out.println("Did you specify a valid path to a service account key file?");
      System.exit(1);
    } catch (GeneralSecurityException ex) {
      System.out.printf("Unable to establish secure HttpTransport:%n%s", ex);
      System.exit(1);
    }

    try {
      execute(
          client,
          parsedArgs.getLong("account_id"),
          parsedArgs.getString("report_id"));
    } catch (IOException ex) {
      System.out.printf("Agencies & Brands API returned error response:%n%s", ex);
      System.exit(1);
    }
  }
}
```

Running a report is an asynchronous long-running operation. When you call the
`run` method, the Agencies \& Brands API responds with an
[`Operation`](https://developers.google.com/authorized-buyers/agencies-and-brands/apis/agenciesandbrands/reference/rest/v1/agencies.reports.operations#Operation)
resource. The `name` field of the operation identifies the run operation and has
the following format:

    agencies/ACCOUNT_ID/reports/REPORT_ID/operations/OPERATION_ID

The returned `Operation` object contains the following:

- `name`: the server-assigned name for the long-running operation. The <var translate="no">REPORT_ID</var> is a unique identifier for the report template you have run. The <var translate="no">OPERATION_ID</var> is a unique identifier Google assigns to the operation you create when you run a report template.
- `metadata`: optional service-specific progress information. The `metadata` field might not be populated in the `Operation` object that you receive in the `agencies.reports.run` response.

After initiating a report run, you can't view the report results until the
operation's `done` field is the `true` value. The length of time a report run
takes to complete varies based on the complexity of the report.

## Next steps

- Learn how to [poll and view completed reports](https://developers.google.com/authorized-buyers/agencies-and-brands/apis/guides/agenciesandbrands/reports/poll-view-completed-reports) with the Agencies \& Brands API.
- Learn how to [view existing reports](https://developers.google.com/authorized-buyers/agencies-and-brands/apis/guides/agenciesandbrands/reports/view) with the Agencies \& Brands API.