How do I use date expressions in data source 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
• Common queries
• Validating date expressions

Where to use date expressions

Date expressions can be used in the request fields you configure during data source 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()}

Common queries

You can copy these example queries and change the date parameters in curly braces to suit your data.

Google Ads

The query goes in the Query URL field. The default example retrieves the last month to today:

SELECT Amount, Period, Ctr, Clicks, ConversionRate, Cost,
       CostPerConversion, Date, Impressions, ConversionValue
FROM CAMPAIGN_PERFORMANCE_REPORT
DURING {date.addMonths(-1).format('yyyyMMdd')}, {date.today.format('yyyyMMdd')}

To use a different date range, replace the DURING clause with one of these:

• Last 7 days: DURING {date.add(-7).format('yyyyMMdd')}, {date.today.format('yyyyMMdd')}
• From the start of last month to today: DURING {date.addMonths(-1).startOfMonth.format('yyyyMMdd')}, {date.today.format('yyyyMMdd')}

Google Analytics

Google Analytics uses a POST request, so the date expressions go in the Query Body field.

Query URL:

https://analyticsdata.googleapis.com/v1beta/properties/{propertyID}:runReport

Query Body (last 30 days to today):

{
  "dimensions": [
    { "name": "date" },
    { "name": "defaultChannelGroup" },
    { "name": "eventName" },
    { "name": "pagePath" }
  ],
  "metrics": [
    { "name": "conversions" },
    { "name": "engagementRate" },
    { "name": "sessions" },
    { "name": "totalUsers" },
    { "name": "userConversionRate" }
  ],
  "dateRanges": [
    {
      "startDate": "{date.last30Days}",
      "endDate": "{date.today}"
    }
  ]
}

To use a different date range, replace the dateRanges entry with one of these:

• Last 3 months to today:
  { "startDate": "{date.addMonths(-3).format()}", "endDate": "{date.today}" }
   
• All of last year:
  { "startDate": "{date.addYears(-1).startOfYear.format()}", "endDate": "{date.addYears(-1).endOfYear.format()}" }
   
• From the start of the month three months ago to today:
  { "startDate": "{date.addMonths(-3).startOfMonth.format()}", "endDate": "{date.today}" }

Facebook

The date expressions go in the Query URL field. The default example retrieves the last 90 days:

https://graph.facebook.com/v2.5/insights/page_views/day?since={date.add(-90).format()}&until={date.today}

For the last 30 days instead, use:

since={date.last30Days}&until={date.today}

Validating date expressions

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

1. Click Data Sources in the left navigation sidebar.
2. On the data source list page, click Create a new data source.
3. Under Additional options, select REST/URL.
4. 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.