How do I use date expressions in queries to retrieve dynamic date ranges?

Date expressions (also called dynamic date parameters) let you define a date or time relative to the current date, so a query can retrieve data for a moving time range — for example, from the start of the month to today, or for the previous week. The date expression is re-evaluated on every data feed refresh, so the range slides forward automatically instead of being hard-coded.

This article covers:

• Where to use date expressions
• Date formats
• Date expression syntax
• Date method reference guide
• Examples
• Validating date expressions

Where to use date expressions

Date expressions can be used in the request fields you configure during data feed creation, for example, in the Query URL (including its query string) or in the Query Body for POST requests.

A date parameter in a query can also be set to a hard-coded value, for example 2025-12-12. Use a date expression instead whenever the range should move with the current date.

Date formats

Date formats refer to how a date is represented as text. For example, December 1, 2025 can be represented as:

• December 1, 2025(format MMMM d, yyyy)
• 01-12-2025 (format dd-MM-yyyy)
• 1764547200 (Unix time — the number of seconds elapsed since midnight January 1, 1970 UTC)

Date expression syntax

Date expressions start with the keyword date, followed by a chain of methods in a fixed order, all contained in curly braces. Square brackets mark optional parts (the brackets aren’t part of the syntax), and ... means a part can repeat:

{date[.setMethod][.dateSetting ...][.manipulationMethod ...][.dateShortcut][.formatMethod]}

The keyword date is required, and may be followed by, in this order:

• at most one set method
• any number of date settings
• any number of manipulation methods
• at most one date shortcut
• at most one format method

Date methods return values in EST by default. Note that this is fixed EST (UTC−5) year-round; it does not observe daylight saving time. During daylight saving, Eastern local time is UTC−4, so default date/time values run one hour behind Eastern wall-clock time, and day boundaries (today, yesterday, startOfWeek, etc.) change at 1:00 AM local Eastern rather than midnight. For Eastern local time that observes daylight saving, use tz("America/New_York"). tz() accepts full region time zone IDs and short codes.

Method names are case-sensitive: Use last30Days, not last30days.

Date expression syntax examples:

• {date.addMonths(-1).format('yyyyMMdd')} — manipulation method + format method. One month ago, formatted as yyyyMMdd.
• {date.firstDOW("mon").addWeeks(-1).startOfWeek.format()} — date setting + manipulation method + date shortcut + format method. The start of the previous week, where weeks begin on Monday.
• {date.today} — date shortcut only. Today's date in the default yyyy-MM-dd format.

Date method reference guide

date (required keyword)

Set methods (zero or one per expression)

Set methods set the date/time to a specific value.

Date settings (zero or more per expression)

Date settings define the time zone, first day of the week, and first month of the year.

Date manipulation methods (zero or more per expression)

Date manipulation methods add or subtract units of time. Use negative numbers to subtract.

Note: To add or subtract days, use add(n).

Date shortcuts (zero or one per expression)

Date shortcuts set the date/time and return it in yyyy-MM-dd format by default.

Shortcuts behave in two distinct ways:

• today, yesterday, last7Days, last30Days, and last60Days are absolute: they reset the date relative to the current date/time, discarding any set or manipulation methods earlier in the chain. For example, {date.set("2026-01-31").today} returns today's date, not January 31.
• The startOf... and endOf... shortcuts are relative: they adjust whatever date the chain has produced so far. This is why {date.addMonths(-1).startOfMonth} returns the start of the previous month.

Format methods (zero or one per expression)

A format method is required when:

• no date shortcut is used in the expression, or
• a date shortcut is used but you need a format other than the default yyyy-MM-dd.

If an expression doesn’t contain a date shortcut or a format method, it does not resolve to a date. Instead, it renders in the request as an internal object reference which the target API will reject. If you see a string like this in a request, a response, or an error message, add .format() (or a date shortcut) to the end of the expression.

Examples

From the start of the current quarter to today at noon (CST), default format. Retrieves data from the first day of the current quarter at 00:00:00 to the current date at 12:00:00:

https://www.webservice.com/data?start-date={date.tz("cst").startOfQuarter}&end-date={date.set("12:00:00","HH:mm:ss").today}

From the start of the previous year to now, in Unix time:

https://www.webservice.com/data?start-date={date.addYears(-1).startOfYear.format("unixtime")}&end-date={date.today.format("unixtime")}

Unix time in milliseconds. Some web service APIs require date/times in Unix time as milliseconds; append 000 to the unix time parameter:

https://www.webservice.com/data?start-date={date.add(-7).format('unixtime')}000&end-date={date.today.format("unixtime")}000

From the start of the fiscal year to today, where the fiscal year starts April 1st (uses firstMOY):

https://www.webservice.com/data?start-date={date.firstMOY("apr").startOfYear.format()}&end-date={date.today}

The previous week, where the week starts on Monday (uses firstDOW):

https://www.webservice.com/data?start-date={date.firstDOW("mon").addWeeks(-1).startOfWeek.format()}&end-date={date.firstDOW("mon").addWeeks(-1).endOfWeek.format()}

Validating date expressions

To validate the results returned by a date expression, create a REST/URL data feed in PowerMetrics (you don't need to save it):

1. Click the + button beside Data Feeds in the left navigation sidebar.
2. Click Select data.
3. On the Where is your data? page, select REST/URL.
4. On the Configure data service page, set Query URL to: https://httpbin.org/get?<fromDate>&<toDate> where <fromDate> and <toDate> are the date parameters from your query.
   For example, if the date parameters are from={date.addHours(-15).format("yyyy-MM-dd'T'HH:mm:ssZ")} and to={date.today.format()}, set the Query URL to:
   https://httpbin.org/get?from={date.addHours(-15).format("yyyy-MM-dd'T'HH:mm:ssZ")}&to={date.today.format()} 
5. Set Data Format to JSON and Method to GET.
6. Click Get data. The resolved date values are listed under the args object in the response.
7. Click Cancel to exit.