REST Resource: queries

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

Resource: Query

Represents a query.

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

string (int64 format)

Output only. Query ID.

metadata

object (QueryMetadata)

Query metadata.

params

object (Parameters)

Query parameters.

schedule

object (QuerySchedule)

Information on how often and when to run a query.

If ONE_TIME is set to the frequency field, the query will only be run at the time of creation.

QueryMetadata

Query metadata.

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

string

Query title. It is used to name the reports generated from this query.

dataRange

object (DataRange)

Range of report data.

All reports will be based on the same time zone as used by the advertiser.

format

enum (Format)

Format of the generated report.

sendNotification

boolean

Whether to send an email notification when a report is ready. Defaults to false.

shareEmailAddress[]

string

List of email addresses which are sent email notifications when the report is finished. Separate from sendNotification.

DataRange

Report data range.

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

enum (Range)

Report data range used to generate the report.

customStartDate

object (Date)

The starting data for the data that is shown in the report. Note, customStartDate is required if range is CUSTOM_DATES and ignored otherwise.

customEndDate

object (Date)

The ending date for the data that is shown in the report. Note, customEndDate is required if range is CUSTOM_DATES and ignored otherwise.

Range

Available report data ranges.

Enums
RANGE_UNSPECIFIED Default value when range is not specified or is unknown in this version.
CUSTOM_DATES Custom range specified by customStartDate and customEndDate fields.
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

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

When to start running the query. Not applicable to ONE_TIME frequency.

endDate

object (Date)

Date to periodically run the query until. Not applicable to ONE_TIME frequency.

frequency

enum (Frequency)

How often the query is run.

nextRunTimezoneCode

string

Canonical timezone code for report generation time. 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 once.
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 query.

delete

Deletes a query as well as the associated reports.

get

Retrieves a query.

list

Lists queries created by the current user.

run

Runs a stored query to generate a report.