Date ranges

Page Summary

outlined_flag

• The Google Ads Query Language supports specifying date ranges using custom dates, predefined date ranges, and predefined time periods.

• Custom date ranges can be specified using ISO 8601 format, either extended (YYYY-MM-DD) or basic (YYYYMMDD).

• Predefined date ranges allow you to query data for common periods like TODAY, YESTERDAY, LAST_7_DAYS, THIS_MONTH, etc.

• Predefined time periods like segments.week, segments.month, and segments.quarter can be filtered using the = operator with the first day of the period.

The Google Ads Query Language lets you specify the date range in these ways:

• Custom date range
• Predefined date range
• Predefined time period
• Historical lookback limits

Custom date range

You can specify dates in ISO 8601 extended (YYYY-MM-DD) or basic (YYYYMMDD) format. The extended format (YYYY-MM-DD) is recommended for readability. Use BETWEEN or comparison operators (=, >, >=, <, <=) with custom date strings:

segments.date BETWEEN '2026-01-01' AND '2026-01-31'

segments.date >= '20260701' AND segments.date <= '20260731'

Predefined date range

Use the DURING operator with predefined date range literals. The DURING operator supports only predefined date ranges and cannot be used with custom date strings.

The list of valid predefined date ranges is as follows:

Example:

segments.date DURING LAST_30_DAYS

Predefined time period

Some date fields refer to a predefined period of time, specifically:

• segments.week
• segments.month
• segments.quarter

When filtering on these segments with custom date strings (using =, BETWEEN, >=, <=, >, or <), you must specify a date that is the first day of the time period:

• segments.week: Monday of the week (for example, '2026-05-04').
• segments.month: First day of the month (YYYY-MM-01, for example, '2026-05-01').
• segments.quarter: First day of the calendar quarter (YYYY-01-01, YYYY-04-01, YYYY-07-01, or YYYY-10-01).

If you specify a date that isn't the first day of the period, a QueryError.MISALIGNED_DATE_FOR_FILTER error is returned. You can also filter these segments using the DURING operator with a predefined date range.

For example, to specify the month of May in the year 2026, use the following condition, specifying the first day of that month:

segments.month = '2026-05-01'

Historical lookback limits

Historical reporting data availability depends on the granularity of the selected or filtered date segments:

• Daily, weekly, and hourly granularity (segments.date, segments.week, and segments.hour): Supports a lookback window of up to 37 months. Queries that segment by segments.date, segments.week, or segments.hour (or filter on a sub-monthly date range) for dates beyond the 37-month window fail with DateRangeError.REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED in v24 and later (or DateRangeError.UNKNOWN in v23).
• Monthly, quarterly, yearly, or unsegmented granularity (segments.month, segments.quarter, segments.year, or no date segment): Supports up to 11 years of historical data. To query historical data beyond the 37-month window, segment by segments.month, segments.quarter, segments.year, or omit date segments in SELECT, and ensure the WHERE date range starts on the first day of a month and ends on the last day of a month (or filters on segments.month, segments.quarter, or segments.year).