REST Resource: queries

  • The Query resource represents a single query used to generate a report and includes metadata, parameters, and schedule.

  • QueryMetadata contains information about the query such as its title, data range, format, and notification settings.

  • DataRange defines the date range for the report, which can be a preset range or custom dates.

  • QuerySchedule specifies the frequency and duration for automated query runs.

  • Available methods for managing queries include creating, deleting, getting, listing, and running queries.

Resource: Query

A single query used to generate a report.

JSON representation 
{
  "queryId": string,
  "metadata": {
    object (QueryMetadata)
  },
  "params": {
    object (Parameters)
  },
  "schedule": {
    object (QuerySchedule)
  }
}
Fields
queryId

string (int64 format)

Output only. The unique ID of the query.
metadata

object (QueryMetadata)

The metadata of the query.
params

object (Parameters)

The parameters of the report generated by the query.
schedule

object (QuerySchedule)

When and how often the query is scheduled to run.

If the frequency field is set to ONE_TIME, the query will only run when queries.run is called.

QueryMetadata

The metadata of the query.

JSON representation 
{
  "title": string,
  "dataRange": {
    object (DataRange)
  },
  "format": enum (Format),
  "sendNotification": boolean,
  "shareEmailAddress": [
    string
  ]
}
Fields
title

string

The display name of the query.

This value will be used in the file name of reports generated by the query.
dataRange

object (DataRange)

The date range the report generated by the query will report on.

This date range will be defined by the time zone as used by the advertiser.
format

enum (Format)

The format of the report generated by the query.
sendNotification

boolean

Whether an email notification is sent to the query creator when a report generated by the query is ready. This value is false by default.
shareEmailAddress[]

string

List of additional email addresses with which to share the query. If sendNotification is true, these email addresses will receive a notification when a report generated by the query is ready.

If these email addresses are connected to Display & Video 360 users, the query will be available to them in the Display & Video 360 interface.

DataRange

The date range to be reported on.

JSON representation 
{
  "range": enum (Range),
  "customStartDate": {
    object (Date)
  },
  "customEndDate": {
    object (Date)
  }
}
Fields
range

enum (Range)

The preset date range to be reported on.

If CUSTOM_DATES is assigned to this field, fields customStartDate and customEndDate must be set to specify the custom date range.
customStartDate

object (Date)

If CUSTOM_DATES is assigned to range, this field specifies the starting date for the date range that is reported on.

This field is required if using CUSTOM_DATES range and will be ignored otherwise.
customEndDate

object (Date)

If CUSTOM_DATES is assigned to range, this field specifies the end date for the date range that is reported on.

This field is required if using CUSTOM_DATES range and will be ignored otherwise.

Range

Available date ranges.

Enums
RANGE_UNSPECIFIED Default value when range is not specified or is unknown in this version.
CUSTOM_DATES Custom date range.
CURRENT_DAY Current day.
PREVIOUS_DAY Previous day.
WEEK_TO_DATE All days, including the current day, since the most recent Sunday.
MONTH_TO_DATE All days, including the current day, since the start of the current month.
QUARTER_TO_DATE All days, including the current day, since the start of the current quarter.
YEAR_TO_DATE All days, including the current day, since the start of the current calendar year.
PREVIOUS_WEEK The previous completed week, beginning from Sunday.
PREVIOUS_MONTH The previous completed calendar month.
PREVIOUS_QUARTER The previous completed quarter.
PREVIOUS_YEAR The previous completed calendar year.
LAST_7_DAYS The previous 7 days, excluding the current day.
LAST_30_DAYS The previous 30 days, excluding the current day.
LAST_90_DAYS The previous 90 days, excluding the current day.
LAST_365_DAYS The previous 365 days, excluding the current day.
ALL_TIME All time for which data is available, excluding the current day.
LAST_14_DAYS The previous 14 days, excluding the current day.
LAST_60_DAYS The previous 60 days, excluding the current day.

QuerySchedule

Settings on when and how frequently to run a query.

JSON representation 
{
  "startDate": {
    object (Date)
  },
  "endDate": {
    object (Date)
  },
  "frequency": enum (Frequency),
  "nextRunTimezoneCode": string
}
Fields
startDate

object (Date)

The date on which to begin the scheduled runs.

This field is required if frequency is not set to ONE_TIME. Otherwise, it will be ignored.
endDate

object (Date)

The date on which to end the scheduled runs.

This field is required if frequency is not set to ONE_TIME. Otherwise, it will be ignored.
frequency

enum (Frequency)

How frequently to run the query.

If set to ONE_TIME, the query will only be run when queries.run is called.
nextRunTimezoneCode

string

The canonical code for the timezone the query schedule is based on. Scheduled runs are usually conducted in the morning of a given day.

Defaults to America/New_York.

Frequency

Available frequencies in which a query can be scheduled to run.

Enums
FREQUENCY_UNSPECIFIED Default value when frequency is not specified or is unknown in this version.
ONE_TIME Only when the query is run manually.
DAILY Once a day.
WEEKLY Once a week.
SEMI_MONTHLY Twice a month.
MONTHLY Once a month.
QUARTERLY Once a quarter.
YEARLY Once a year.

Methods

create

 Creates a new query.

delete

 Deletes an existing query as well as its generated reports.

get

 Retrieves a query.

list

 Lists queries created by the current user.

run

 Runs an existing query to generate a report.