The [`Report`](https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports#resource:-report)
object defines a reusable template describing a report you want to produce. The
`Report` object configures criteria such as the dimensions, metrics, and the
date range for the report.

This guide describes how you can use the Curation
Partners API to [create](https://developers.google.com/authorized-buyers/curation/apis/guides/curationpartners/reports/create-modify#create_report) a report to track performance,
[modify](https://developers.google.com/authorized-buyers/curation/apis/guides/curationpartners/reports/create-modify#modify_report) an existing report to better fit your needs, or
[delete](https://developers.google.com/authorized-buyers/curation/apis/guides/curationpartners/reports/create-modify#delete_report) a template for an obsolete report.

## Before you begin

Before you continue, you must
[set up authentication](https://developers.google.com/authorized-buyers/curation/apis/guides/curationpartners/overview#set_up_authentication).

## Create a report

You can create a report using the
[`curators.reports.create`](https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports/create)
method. A report configures the dimensions, metrics, date range, time zone,
filters, and default sorts for your reporting queries.

The following example makes a `POST` request to the `curators.reports.create`
method with a JSON body containing a `Report` object:

### REST

#### Request

    curl --request POST \
      'https://curationpartners.googleapis.com/v1/curators/ACCOUNT_ID/reports' \
      --header 'Authorization: Bearer ACCESS_TOKEN' \
      --header 'Accept: application/json' \
      --header 'Content-Type: application/json' \
      --data '{
        "displayName": "Monthly Data Segment Performance",
        "reportDefinition": {
          "dimensions": [
            "DATE",
            "CURATION_DATA_SEGMENT_ID"
          ],
          "metrics": [
            "IMPRESSIONS",
            "CLICKS",
            "SPEND",
            "CURATION_PARTNER_FEE"
          ],
          "dateRange": {
            "relative": "LAST_30_DAYS"
          },
          "timeZoneSource": "UTC"
        }
      }' \
      --compressed

Replace the following:

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

#### Response

    {
      "name": "curators/ACCOUNT_ID/reports/123456789",
      "reportId": "123456789",
      "displayName": "Monthly Data Segment Performance",
      "reportDefinition": {
        "dimensions": [
          "DATE",
          "CURATION_DATA_SEGMENT_ID"
        ],
        "metrics": [
          "IMPRESSIONS",
          "CLICKS",
          "SPEND",
          "CURATION_PARTNER_FEE"
        ],
        "dateRange": {
          "relative": "LAST_30_DAYS"
        },
        "timeZoneSource": "UTC"
      },
      "createTime": "2026-08-01T10:00:00Z",
      "updateTime": "2026-08-01T10:00:00Z",
      "locale": "en"
    }

When creating a report, you must populate the
[`reportDefinition`](https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports#ReportDefinition)
object with the following fields:

- [`dimensions`](https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports#Dimension): the list of dimensions you can use to group the metrics in your report, such as `DATE`, `CURATION_DATA_SEGMENT_ID`, `DEAL_ID`, or `ENVIRONMENT`.
- [`metrics`](https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports#Metric): the list of metrics to aggregate, such as `IMPRESSIONS`, `CLICKS`, `SPEND`, or `CURATION_PARTNER_FEE`.
- [`dateRange`](https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports#DateRange): the date range for the report. The date range is specified as either a range relative to when the report is run such as `LAST_30_DAYS` or `YESTERDAY`, or a fixed range with `startDate` and `endDate`.

You can optionally configure the following fields:

- [`timeZoneSource`](https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports#TimeZoneSource): The source of the time zone applied to the report. Defaults to the `AD_EXCHANGE` enum value, which uses the Pacific time zone.
- [`timeZone`](https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports#ReportDefinition.FIELDS.time_zone): An IANA time zone string---for example, `"America/New_York"`. You must populate this field when you set the `timeZoneSource` field to the `PROVIDED` value.
- [`filters`](https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports#Filter): Restricts report data to specific dimension or metric values you specify.
- [`sorts`](https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports#Sort):
  Default sort ordering for report result rows.

### 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;

import com.google.api.services.curationpartners.v1.CurationPartners;
import com.google.api.services.curationpartners.v1.model.DateRange;
import com.google.api.services.curationpartners.v1.model.Report;
import com.google.api.services.curationpartners.v1.model.ReportDefinition;
import com.google.api.services.samples.curationpartners.v1.Utils;
import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.List;
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 CreateReport {

  /**
   * Executes the create operation for a report.
   *
   * @param curationPartnersClient the initialized Curation Partners API client.
   * @param accountId the account ID of the curator that will create the report.
   * @param displayName the display name of the report to be created.
   * @param dimensions the list of dimensions to include in the report definition.
   * @param metrics the list of metrics to include in the report definition.
   * @param relativeDateRange the relative date range for the report.
   * @throws IOException if the API returns an error.
   */
  public static void execute(
      CurationPartners curationPartnersClient,
      Long accountId,
      String displayName,
      List<String> dimensions,
      List<String> metrics,
      String relativeDateRange)
      throws IOException {
    String parent = String.format("curators/%s", accountId);

    System.out.printf("Creating Report \"%s\" for curator with name \"%s\".%n",
        displayName, parent);

    ReportDefinition reportDefinition =
        new ReportDefinition()
            .setDimensions(dimensions)
            .setMetrics(metrics)
            .setDateRange(new DateRange().setRelative(relativeDateRange));

    Report newReport =
        new Report()
            .setDisplayName(displayName)
            .setReportDefinition(reportDefinition);

    // Create a new report.
    Report createdReport =
        curationPartnersClient
            .curators()
            .reports()
            .create(parent, newReport)
            .execute();

    System.out.println("Successfully created report:");
    Utils.jsonPrettyPrint(createdReport);
  }

  /**
   * Creates and configures the ArgumentParser for this sample.
   *
   * @return the configured ArgumentParser.
   */
  private static ArgumentParser createArgumentParser() {
    ArgumentParser parser =
        ArgumentParsers.newFor("CreateReport")
            .build()
            .defaultHelp(true)
            .description("Creates a new report for the given curator account.");

    // Required arguments.
    parser
        .addArgument("-a", "--account_id")
        .help("The account ID of the curator that will create the report.")
        .required(true)
        .type(Long.class);
    parser
        .addArgument("-d", "--display_name")
        .help("The display name of the report to be created.")
        .required(true);
    parser
        .addArgument("--dimensions")
        .help("The space-delimited list of dimensions to include in the report definition " +
            "(for example: DATE BUYER_NAME). For a listing of possible values, see: " +
            "https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports#dimension")
        .required(true)
        .nargs("+");
    parser
        .addArgument("--metrics")
        .help("The space-delimited list of metrics to include in the report definition " +
            "(for example: IMPRESSIONS CLICKS). For a listing of possible values, see: " +
            "https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports#metric")
        .required(true)
        .nargs("+");

    // Optional arguments.
    parser
        .addArgument("--relative_date_range")
        .help("The relative date range for the report to include in the report definition. (for example: LAST_7_DAYS, TODAY, YESTERDAY). " +
            "Defaults to LAST_7_DAYS if unspecified. For a listing of possible values, see: " +
            "https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports#relativedaterange")
        .setDefault("LAST_7_DAYS");

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

    Long accountId = parsedArgs.getLong("account_id");
    String displayName = parsedArgs.getString("display_name");
    List<String> dimensions = parsedArgs.getList("dimensions");
    List<String> metrics = parsedArgs.getList("metrics");
    String relativeDateRange = parsedArgs.getString("relative_date_range");

    try {
      execute(client, accountId, displayName, dimensions, metrics, relativeDateRange);
    } catch (IOException ex) {
      System.out.printf("Curation Partners API returned error response:%n%s", ex);
      System.exit(1);
    }
  }
}
```

## Modify an existing report

To modify an existing report, use the
[`curators.reports.patch`](https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports/patch)
method. To specify which fields to update, use the `updateMask` query
parameter.

The following example makes a `PATCH` request to update the display name and
relative date range of a report:

### REST

#### Request

    curl --request PATCH \
      'https://curationpartners.googleapis.com/v1/curators/ACCOUNT_ID/reports/123456789?updateMask=displayName,reportDefinition.dateRange.relative' \
      --header 'Authorization: Bearer ACCESS_TOKEN' \
      --header 'Accept: application/json' \
      --header 'Content-Type: application/json' \
      --data '{
        "displayName": "Updated Data Segment Performance",
        "reportDefinition": {
          "dateRange": {
            "relative": "THIS_MONTH_TO_DATE"
          }
        }
      }' \
      --compressed

#### Response

    {
      "name": "curators/ACCOUNT_ID/reports/123456789",
      "reportId": "123456789",
      "displayName": "Updated Data Segment Performance",
      "reportDefinition": {
        "dimensions": [
          "DATE",
          "CURATION_DATA_SEGMENT_ID"
        ],
        "metrics": [
          "IMPRESSIONS",
          "CLICKS",
          "SPEND",
          "CURATION_PARTNER_FEE"
        ],
        "dateRange": {
          "relative": "THIS_MONTH_TO_DATE"
        },
        "timeZoneSource": "UTC"
      },
      "createTime": "2026-08-01T10:00:00Z",
      "updateTime": "2026-08-01T10:10:00Z",
      "locale": "en"
    }

### 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;

import com.google.api.services.curationpartners.v1.CurationPartners;
import com.google.api.services.curationpartners.v1.model.DateRange;
import com.google.api.services.curationpartners.v1.model.Report;
import com.google.api.services.curationpartners.v1.model.ReportDefinition;
import com.google.api.services.samples.curationpartners.v1.Utils;

import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.ArrayList;
import java.util.List;
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 PatchReport {

  private PatchReport() {}

  /**
   * Executes the patch operation for a report.
   *
   * @param curationPartnersClient the initialized Curation Partners API client.
   * @param accountId the account ID of the curator that created the report.
   * @param reportId the resource ID of the report to update.
   * @param displayName the modified display name for the report (or null if not being modified).
   * @param relativeDateRange the modified relative date range for the report definition (or null
   *     if not being modified).
   * @param dimensions the modified list of dimensions for the report definition (or null if not
   *     being modified).
   * @param metrics the modified list of metrics for the report definition (or null if not being
   *     modified).
   * @throws IOException if the API returns an error.
   */
  public static void execute(
      CurationPartners curationPartnersClient,
      Long accountId,
      String reportId,
      String displayName,
      String relativeDateRange,
      List<String> dimensions,
      List<String> metrics)
      throws IOException {

    String name = String.format("curators/%d/reports/%s", accountId, reportId);

    List<String> patchedFields = new ArrayList<>();
    Report patchedReport = new Report();

    if (displayName != null) {
      patchedReport.setDisplayName(displayName);
      patchedFields.add("displayName");
    }

    ReportDefinition reportDefinition = new ReportDefinition();
    if (relativeDateRange != null) {
      reportDefinition.setDateRange(new DateRange().setRelative(relativeDateRange));
      patchedFields.add("reportDefinition.dateRange.relative");
    }
    if (dimensions != null) {
      reportDefinition.setDimensions(dimensions);
      patchedFields.add("reportDefinition.dimensions");
    }
    if (metrics != null) {
      reportDefinition.setMetrics(metrics);
      patchedFields.add("reportDefinition.metrics");
    }
    // Set the ReportDefinition on the patched Report unconditionally. Any fields not
    // explicitly specified in the updateMask will be ignored by the API.
    patchedReport.setReportDefinition(reportDefinition);

    if (patchedFields.isEmpty()) {
      System.out.println("No fields specified to update.");
      return;
    }

    String updateMask = String.join(",", patchedFields);

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

    // Patch the report.
    Report returnedReport =
        curationPartnersClient
            .curators()
            .reports()
            .patch(name, patchedReport)
            .setUpdateMask(updateMask)
            .execute();

    System.out.println("Successfully patched report:");
    Utils.jsonPrettyPrint(returnedReport);
  }

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

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

    // Optional arguments.
    parser
        .addArgument("-d", "--display_name")
        .help("The modified display name of the report.");
    parser
        .addArgument("--relative_date_range")
        .help("The modified relative date range for the report definition (for example: " +
            "LAST_7_DAYS, TODAY, YESTERDAY). For a listing of possible values, see: " +
            "https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports#relativedaterange");
    parser
        .addArgument("--dimensions")
        .help("A space-delimited list of modified dimensions for the report definition (for " +
            "example: DATE, BUYER_NAME). For a listing of possible values, see: " +
            "https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports#dimension")
        .nargs("+");
    parser
        .addArgument("--metrics")
        .help("A space-delimited list of modified metrics for the report definition (for " +
            "example: IMPRESSIONS CLICKS). For a listing of possible values, see: " +
            "https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports#metric")
        .nargs("+");

    return parser;
  }

  public static void main(String[] args) {
    ArgumentParser parser = createArgumentParser();
    Namespace parsedArgs = null;
    try {
      parsedArgs = parser.parseArgs(args);
    } catch (ArgumentParserException e) {
      parser.handleError(e);
      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);
    }

    Long accountId = parsedArgs.getLong("account_id");
    String reportId = parsedArgs.getString("report_id");
    String displayName = parsedArgs.getString("display_name");
    String relativeDateRange = parsedArgs.getString("relative_date_range");
    List<String> dimensions = parsedArgs.getList("dimensions");
    List<String> metrics = parsedArgs.getList("metrics");

    try {
      execute(
          client, accountId, reportId, displayName, relativeDateRange, dimensions, metrics);
    } catch (IOException e) {
      System.out.printf("Curation Partners API returned error response:%n%s", e);
      System.exit(1);
    }
  }
}
```

## Delete a report

To delete a report you no longer need, use the
[`curators.reports.delete`](https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports/delete)
method. After you delete a report, you can no longer use the report for future
report runs. You also can't retrieve the report with the `curators.reports.get`
or `curators.reports.list` methods.

The following example sends a `DELETE` request to delete the specified report:

### REST

#### Request

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

#### Response

    {}

### 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;

import com.google.api.services.curationpartners.v1.CurationPartners;
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 DeleteReport {

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

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

    // Delete the specified report.
    curationPartnersClient.curators().reports().delete(name).execute();

    System.out.println("Successfully deleted report.");
  }

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

    // Required arguments.
    parser
        .addArgument("-a", "--account_id")
        .help("The account ID of the curator that created the report.")
        .required(true)
        .type(Long.class);
    parser
        .addArgument("-r", "--report_id")
        .help("The resource ID of the report to delete.")
        .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"));
    } catch (IOException ex) {
      System.out.printf("Curation Partners API returned error response:%n%s", ex);
      System.exit(1);
    }
  }
}
```

## Next steps

- Learn how to [view 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.
- Learn how to [poll and view completed reports](https://developers.google.com/authorized-buyers/curation/apis/guides/curationpartners/reports/poll-view-completed-reports) with the Curation Partners API.