Create and modify reports

The 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 a report to track performance, modify an existing report to better fit your needs, or delete a template for an obsolete report.

Before you begin

Before you continue, you must set up authentication.

Create a report

You can create a report using the 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 object with the following fields:

dimensions: 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: the list of metrics to aggregate, such as IMPRESSIONS, CLICKS, SPEND, or CURATION_PARTNER_FEE.
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: The source of the time zone applied to the report. Defaults to the AD_EXCHANGE enum value, which uses the Pacific time zone.
timeZone: 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: Restricts report data to specific dimension or metric values you specify.
sorts: Default sort ordering for report result rows.

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

/*
 * 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 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

/*
 * 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 with the Curation Partners API.
Learn how to run reports with the Curation Partners API.
Learn how to poll and view completed reports with the Curation Partners API.

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

Before you begin

Create a report

REST

Request

Response

Java

Modify an existing report

REST

Request

Response

Java

Delete a report

REST

Request

Response

Java

Next steps

Create and modify reports