A report run operation executes asynchronously as a long-running operation,
represented by the
[`Operation`](https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports.operations#resource:-operation)
object. The output of a report run operation are report results based on the
[`Report`](https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports#resource:-report)
object.

This guide describes how you can use the Curation Partners API to
[get](https://developers.google.com/authorized-buyers/curation/apis/guides/curationpartners/reports/poll-view-completed-reports#poll_report_run) a report run operation to poll the operation's status,
and [fetch](https://developers.google.com/authorized-buyers/curation/apis/guides/curationpartners/reports/poll-view-completed-reports#fetch_report_rows) the report results of the completed report run
operation.

> [!IMPORTANT]
> **Important:** Both report run operations and their corresponding results have a retention period of seven days. After the retention period, the Curation Partners API returns an error response if you poll the report run operation or fetch the report results.

## Before you begin

Before you continue, you must complete the following:

- [Set up authentication](https://developers.google.com/authorized-buyers/curation/apis/guides/curationpartners/overview#set_up_authentication).
- [Initiate a report run](https://developers.google.com/authorized-buyers/curation/apis/guides/curationpartners/reports/run#run_report) to obtain a long-running operation resource name.

## Poll status of a report run

To check the execution status of a report run operation, use the
[`curators.reports.operations.get`](https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports.operations/get)
method.

The following example makes a `GET` request to poll an operation:

### REST

#### Request

    curl \
      'https://curationpartners.googleapis.com/v1/curators/ACCOUNT_ID/reports/123456789/operations/10486370264' \
      --header 'Authorization: Bearer ACCESS_TOKEN' \
      --header 'Accept: application/json' \
      --compressed

Replace the following:

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

#### Response

When completed successfully, the response is an `Operation` with the `done`
field set to `true`, and the `response` payload is populated with the
`reportResult` resource name:

    {
      "name": "curators/ACCOUNT_ID/reports/123456789/operations/10486370264",
      "done": true,
      "metadata": {
        "@type": "type.googleapis.com/google.ads.curationpartners.v1.RunReportMetadata",
        "percentComplete": 100
      },
      "response": {
        "@type": "type.googleapis.com/google.ads.curationpartners.v1.RunReportResponse",
        "reportResult": "curators/ACCOUNT_ID/reports/123456789/results/10486370264"
      }
    }

### 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.curationpartners.v1.curators.reports.operations;

import com.google.api.services.curationpartners.v1.CurationPartners;
import com.google.api.services.curationpartners.v1.model.Operation;
import com.google.api.services.samples.curationpartners.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 GetReportOperation {

  /**
   * Executes the get operation for a report operation.
   *
   * @param curationPartnersClient the initialized Curation Partners API client.
   * @param accountId the account ID of the curator.
   * @param reportId the resource ID of the report.
   * @param operationId the resource ID of the report operation.
   * @throws IOException if the API returns an error.
   */
  public static void execute(
      CurationPartners curationPartnersClient,
      Long accountId,
      String reportId,
      String operationId)
      throws IOException {
    String name =
        String.format(
            "curators/%s/reports/%s/operations/%s", accountId, reportId, operationId);

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

    // Get the status of the report operation.
    Operation operation =
        curationPartnersClient
            .curators()
            .reports()
            .operations()
            .get(name)
            .execute();

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

  /**
   * Creates and configures the ArgumentParser for this sample.
   *
   * @return the configured ArgumentParser.
   */
  private static ArgumentParser createArgumentParser() {
    ArgumentParser parser =
        ArgumentParsers.newFor("GetReportOperation")
            .build()
            .defaultHelp(true)
            .description("Gets the status of a long-running report operation. If the " +
                "operation is done, you can view the report contents with the " +
                "`curators.reports.results.fetchRows` method.");

    // Required arguments.
    parser
        .addArgument("-a", "--account_id")
        .help("The account ID of the curator.")
        .required(true)
        .type(Long.class);
    parser
        .addArgument("-r", "--report_id")
        .help("The resource ID of the report.")
        .required(true);
    parser
        .addArgument("-o", "--operation_id")
        .help("The resource ID of the report operation to retrieve.")
        .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);
    }

    CurationPartners client = null;
    try {
      client = Utils.getCurationPartnersClient();
    } catch (IOException ex) {
      System.out.printf("Unable to create Curation Partners 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"),
          parsedArgs.getString("operation_id"));
    } catch (IOException ex) {
      System.out.printf("Curation Partners API returned error response:%n%s", ex);
      System.exit(1);
    }
  }
}
```

The following describes how you can use the `done` field to poll the status of
the operation:

- If the `done` field in the response is the `false` value, the report run operation is still processing.
- If the `done` field in the response is the `true` value, the report run operation is complete. The `Operation` object in the response body also contains either of the following fields:
  - `response`: Indicates that the report run operation is successful. This field is an object populated with a `@type` field set to the `type.googleapis.com/google.ads.curationpartners.v1.RunReportResponse` type. The `RunReportResponse` type is populated with a `reportResult` field containing the name of the corresponding report [`result`](https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports.results).
  - `error`: Indicates that the report run operation isn't successful. The `error` field is populated with a [`Status`](https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports.operations#Status) object describing why the report run failed.

> [!IMPORTANT]
> **Key Point:** Google recommends polling with an exponential backoff algorithm starting with a duration of 30 seconds.

> [!TIP]
> **Tip:** The operation's `metadata` field is populated with `@type` set to `RunReportMetadata`. You can use the `percentComplete` field to receive an estimate of how close the report run operation is to being completed. If the `percentComplete` field isn't populated, the estimated completion percentage for the report run is 0%.

## Fetch rows from a completed report

You can retrieve the contents of a completed report run operation with the
[`curators.reports.results.fetchRows`](https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports.results/fetchRows)
method. You must fill in the `name` path parameter for the report result,
which is the resource name from the `reportResult` field of a complete report
run operation.

The following example makes a `GET` request to fetch result rows:

### REST

#### Request

    curl \
      'https://curationpartners.googleapis.com/v1/curators/ACCOUNT_ID/reports/123456789/results/10486370264:fetchRows?pageSize=1' \
      --header 'Authorization: Bearer ACCESS_TOKEN' \
      --header 'Accept: application/json' \
      --compressed

#### Response

    {
      "rows": [
        {
          "dimensionValues": [
            {
              "stringValue": "2026-08-01"
            },
            {
              "stringValue": "segment-1001"
            }
          ],
          "metricValueGroups": [
            {
              "primaryValues": [
                {
                  "intValue": "150000"
                },
                {
                  "intValue": "3200"
                },
                {
                  "doubleValue": 450.75
                },
                {
                  "doubleValue": 45.08
                }
              ]
            }
          ]
        }
      ],
      "runTime": "2026-08-05T12:00:00Z",
      "dateRanges": [
        {
          "startDate": {
            "year": 2026,
            "month": 7,
            "day": 6
          },
          "endDate": {
            "year": 2026,
            "month": 8,
            "day": 4
          }
        }
      ],
      "totalRowCount": 2,
      "nextPageToken": "QC7nzW91c2VTcGFubmVyQ29udGlubWF0aW6uVG9wZY45NP=="
    }

### 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.curationpartners.v1.curators.reports.results;

import com.google.api.services.curationpartners.v1.CurationPartners;
import com.google.api.services.curationpartners.v1.model.FetchReportResultRowsResponse;
import com.google.api.services.samples.curationpartners.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 FetchReportResultRows {

  /**
   * Executes the fetchRows operation for report result rows.
   *
   * @param curationPartnersClient the initialized Curation Partners API client.
   * @param accountId the account ID of the curator.
   * @param reportId the resource ID of the report.
   * @param resultId the resource ID of the report result.
   * @param pageSize the maximum number of rows to return per page.
   * @param pageToken the page token from a previous response, if any.
   * @throws IOException if the API returns an error.
   */
  public static void execute(
      CurationPartners curationPartnersClient,
      Long accountId,
      String reportId,
      String resultId,
      Integer pageSize,
      String pageToken)
      throws IOException {
    String name = String.format("curators/%s/reports/%s/results/%s", accountId, reportId, resultId);

    System.out.printf("Fetching report result rows for \"%s\".%n", name);

    CurationPartners.Curators.Reports.Results.FetchRows request =
        curationPartnersClient.curators().reports().results().fetchRows(name);

    if (pageSize != null) {
      request.setPageSize(pageSize);
    }
    if (pageToken != null) {
      request.setPageToken(pageToken);
    }

    FetchReportResultRowsResponse response = request.execute();

    System.out.println("Successfully fetched report result rows:");
    Utils.jsonPrettyPrint(response);
  }

  /**
   * Creates and configures the ArgumentParser for this sample.
   *
   * @return the configured ArgumentParser.
   */
  private static ArgumentParser createArgumentParser() {
    ArgumentParser parser =
        ArgumentParsers.newFor("FetchReportResultRows")
            .build()
            .defaultHelp(true)
            .description("Fetches rows for a completed report result.");

    // Required arguments.
    parser
        .addArgument("-a", "--account_id")
        .help("The account ID of the curator.")
        .required(true)
        .type(Long.class);
    parser
        .addArgument("-r", "--report_id")
        .help("The resource ID of the report.")
        .required(true);
    parser
        .addArgument("--result_id")
        .help("The resource ID of the report result. This is identical to the resource ID of " +
            "the corresponding report run operation.")
        .required(true);

    // Optional arguments.
    parser
        .addArgument("--page_size")
        .help("The maximum number of rows to return per page.")
        .type(Integer.class);
    parser
        .addArgument("--page_token")
        .help("A page token, received from a previous `FetchReportResultRows` call.");

    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);
    }

    CurationPartners client = null;
    try {
      client = Utils.getCurationPartnersClient();
    } catch (IOException ex) {
      System.out.printf("Unable to create Curation Partners 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"),
          parsedArgs.getString("result_id"),
          parsedArgs.getInt("page_size"),
          parsedArgs.getString("page_token"));
    } catch (IOException ex) {
      System.out.printf("Curation Partners API returned error response:%n%s", ex);
      System.exit(1);
    }
  }
}
```

You can specify the following query parameters:

- `pageSize`: the maximum number of rows to return. The default is 1,000 rows, and the maximum is 10,000 rows.
- `pageToken`: the page token returned in a previous `fetchRows` response to fetch the next batch of rows.

The response contains the following fields:

- [`rows`](https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports.results/fetchRows#Row): An array of `Row` objects. Each row contains:
  - `dimensionValues`: Values for each requested dimension, ordered identically to the dimensions in the report definition.
  - `metricValueGroups`: Groups of metric values corresponding to the date ranges. Each group contains a `primaryValues` list ordered identically to the metrics in the report definition.
- [`dateRanges`](https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports.results/fetchRows#body.FetchReportResultRowsResponse.FIELDS.date_ranges): The computed fixed date ranges for the report. The `dateRanges` field is only included in the response body of the first page.
- [`totalRowCount`](https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports.results/fetchRows#body.FetchReportResultRowsResponse.FIELDS.total_row_count): The total number of rows in the report result. The `totalRowCount` field is only included in the response body of the first page.
- [`nextPageToken`](https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports.results/fetchRows#body.FetchReportResultRowsResponse.FIELDS.next_page_token): Token to pass in subsequent requests to retrieve the next page of rows. If no additional rows exist, the Curation Partners API omits this field from the response body.

In the `curators.reports.results.fetchRows` REST example, each item in `rows`
maps directly to the `ReportDefinition` configured in the report:

- **`dimensionValues`** : contains values corresponding to each dimension in the `reportDefinition.dimensions` field in the exact order you specified. In the example, the first value `2026-08-01` corresponds to the `DATE` dimension, and the second value, `segment-1001`, corresponds to the `CURATION_DATA_SEGMENT_ID` dimension.
- **`metricValueGroups`** : contains metric values grouped in the report's
  date ranges. In each group, the `primaryValues` field contains the values
  corresponding to each metric in the `reportDefinition.metrics` field in the
  exact order you specified. In this example, the four values correspond
  to the following `Metric` enum values:

  - `IMPRESSIONS`: `150000`
  - `CLICKS`: `3200`
  - `SPEND`: `450.75`
  - `CURATION_PARTNER_FEE`: `45.08`
- **`dateRanges`** : contains the fixed date range that Google computed for the
  relative range, `THIS_MONTH_TO_DATE`, configured in the report definition.

## Next steps

- Learn how to [create and modify reports](https://developers.google.com/authorized-buyers/curation/apis/guides/curationpartners/reports/create-modify) with the Curation Partners API.
- Learn how to [view existing reports](https://developers.google.com/authorized-buyers/curation/apis/guides/curationpartners/reports/view) with the Curation Partners API.
- Learn how to [run reports](https://developers.google.com/authorized-buyers/curation/apis/guides/curationpartners/reports/run) with the Curation Partners API.