# Date & Time

Format dates, add time, and find the time between two dates.

## Do things in Date & Time

Add a **Date & Time** step and choose an **Operation**. Choose the row to see the fields of each.

- [Date Operation](https://docs.gorunner.io/apps/date-time#fields-f-operate): Current date/time · Format a date · Add duration · Subtract duration · Difference between dates · Extract part (year/month/...) · Start/end of period · Round a date · Convert timezone · Next weekday

Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list).

## For developers

In the API, which calls apps pieces, Date & Time is `pieceId: "date-helper"` with `actionId: "operate"`, set by `mode` and `operation`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field.

It computes from its inputs only (`pure`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions).

### Date & Time › Date Operation

Work with dates and times.

### Current date/time

- **Format · Optional**: How the date should look in the result, like 2026-06-06 or US-style 06/06/2026. Options: ISO-8601, Date (2006-01-02), Time (15:04:05), Date & time, RFC 1123, Unix timestamp, US (MM/DD/YYYY), EU (DD/MM/YYYY), Custom format. Default: ISO-8601.
- **Custom Format · Optional**: Tokens: YYYY YY MMMM MMM MM DD dddd ddd HH hh mm ss A a Z ZZ (such as YYYY-MM-DD HH:mm). Other text is kept as written; put text in [brackets] to keep it whatever it says. Or a Go reference layout. A format that writes the year as yyyy, yy or y is read as a Luxon pattern instead: yyyy yy y MMMM MMM MM M dd d EEEE EEE HH H hh h mm m ss s SSS S a ZZZ ZZ Z (such as dd.MM.yyyy or yyyy-MM-dd'T'HH:mm:ss); put text in 'single quotes'. Shows when **Format** is **Custom format**.
- **Output Timezone · Optional**: IANA timezone for the output (such as America/New_York). For Next weekday, the zone whose calendar decides what today is. Default: UTC.

### Format a date

- **Date · Required**: An ISO-8601 date/time (such as 2026-06-06T12:00:00Z), a unix timestamp, or an expression from an earlier step.
- **Format · Optional**: How the date should look in the result, like 2026-06-06 or US-style 06/06/2026. Options: ISO-8601, Date (2006-01-02), Time (15:04:05), Date & time, RFC 1123, Unix timestamp, US (MM/DD/YYYY), EU (DD/MM/YYYY), Custom format. Default: ISO-8601.
- **Custom Format · Optional**: Tokens: YYYY YY MMMM MMM MM DD dddd ddd HH hh mm ss A a Z ZZ (such as YYYY-MM-DD HH:mm). Other text is kept as written; put text in [brackets] to keep it whatever it says. Or a Go reference layout. A format that writes the year as yyyy, yy or y is read as a Luxon pattern instead: yyyy yy y MMMM MMM MM M dd d EEEE EEE HH H hh h mm m ss s SSS S a ZZZ ZZ Z (such as dd.MM.yyyy or yyyy-MM-dd'T'HH:mm:ss); put text in 'single quotes'. Shows when **Format** is **Custom format**.
- **Output Timezone · Optional**: IANA timezone for the output (such as America/New_York). For Next weekday, the zone whose calendar decides what today is. Default: UTC.

### Add duration and Subtract duration

- **Date · Required**: An ISO-8601 date/time (such as 2026-06-06T12:00:00Z), a unix timestamp, or an expression from an earlier step.
- **Unit · Optional**: The kind of time to add or subtract, such as days, hours, or months. Options: Milliseconds, Seconds, Minutes, Hours, Days, Weeks, Months, Quarters, Years. Default: Days.
- **Amount · Optional**: How many units to add or subtract, for example 30 to shift by 30 of the chosen unit. Default: 1.
- **Custom Format · Optional**: Tokens: YYYY YY MMMM MMM MM DD dddd ddd HH hh mm ss A a Z ZZ (such as YYYY-MM-DD HH:mm). Other text is kept as written; put text in [brackets] to keep it whatever it says. Or a Go reference layout. A format that writes the year as yyyy, yy or y is read as a Luxon pattern instead: yyyy yy y MMMM MMM MM M dd d EEEE EEE HH H hh h mm m ss s SSS S a ZZZ ZZ Z (such as dd.MM.yyyy or yyyy-MM-dd'T'HH:mm:ss); put text in 'single quotes'. Shows when **Format** is **Custom format**.

### Difference between dates

- **Date · Required**: An ISO-8601 date/time (such as 2026-06-06T12:00:00Z), a unix timestamp, or an expression from an earlier step.
- **Second Date · Required**: The other date to compare against, to measure the gap between the two (such as 2026-07-01).
- **Custom Format · Optional**: Tokens: YYYY YY MMMM MMM MM DD dddd ddd HH hh mm ss A a Z ZZ (such as YYYY-MM-DD HH:mm). Other text is kept as written; put text in [brackets] to keep it whatever it says. Or a Go reference layout. A format that writes the year as yyyy, yy or y is read as a Luxon pattern instead: yyyy yy y MMMM MMM MM M dd d EEEE EEE HH H hh h mm m ss s SSS S a ZZZ ZZ Z (such as dd.MM.yyyy or yyyy-MM-dd'T'HH:mm:ss); put text in 'single quotes'. Shows when **Format** is **Custom format**.
- **Difference in · Optional**: The unit to report the gap between the two dates in, such as days or hours. Options: Milliseconds, Seconds, Minutes, Hours, Days, Weeks, Months, Years. Default: Days.

### Extract part (year/month/...)

- **Date · Required**: An ISO-8601 date/time (such as 2026-06-06T12:00:00Z), a unix timestamp, or an expression from an earlier step.
- **Part · Optional**: Which piece of the date to pull out, such as the year, month, day, or weekday name. Options: Year, Month (number), Day of month, Hour, Minute, Second, Weekday name, ISO week number, Day of year, Month name. Default: Year.
- **Custom Format · Optional**: Tokens: YYYY YY MMMM MMM MM DD dddd ddd HH hh mm ss A a Z ZZ (such as YYYY-MM-DD HH:mm). Other text is kept as written; put text in [brackets] to keep it whatever it says. Or a Go reference layout. A format that writes the year as yyyy, yy or y is read as a Luxon pattern instead: yyyy yy y MMMM MMM MM M dd d EEEE EEE HH H hh h mm m ss s SSS S a ZZZ ZZ Z (such as dd.MM.yyyy or yyyy-MM-dd'T'HH:mm:ss); put text in 'single quotes'. Shows when **Format** is **Custom format**.
- **In Timezone · Optional**: Read the date in this IANA timezone (such as Europe/Berlin) before taking the part, period or rounding; a date written without an offset is a time in this zone. Blank = the date's own offset (UTC for a date without one).

### Start/end of period

- **Date · Required**: An ISO-8601 date/time (such as 2026-06-06T12:00:00Z), a unix timestamp, or an expression from an earlier step.
- **Period · Optional**: The time span to snap the date to, such as the whole day, week, month, or year. Options: Day, Week (from Monday), Month, Year. Default: Day.
- **Boundary · Optional**: Choose whether you want the very beginning or the very end of that period. Options: Start, End. Default: Start.
- **Custom Format · Optional**: Tokens: YYYY YY MMMM MMM MM DD dddd ddd HH hh mm ss A a Z ZZ (such as YYYY-MM-DD HH:mm). Other text is kept as written; put text in [brackets] to keep it whatever it says. Or a Go reference layout. A format that writes the year as yyyy, yy or y is read as a Luxon pattern instead: yyyy yy y MMMM MMM MM M dd d EEEE EEE HH H hh h mm m ss s SSS S a ZZZ ZZ Z (such as dd.MM.yyyy or yyyy-MM-dd'T'HH:mm:ss); put text in 'single quotes'. Shows when **Format** is **Custom format**.
- **In Timezone · Optional**: Read the date in this IANA timezone (such as Europe/Berlin) before taking the part, period or rounding; a date written without an offset is a time in this zone. Blank = the date's own offset (UTC for a date without one).

### Round a date

- **Date · Required**: An ISO-8601 date/time (such as 2026-06-06T12:00:00Z), a unix timestamp, or an expression from an earlier step.
- **Mode · Optional**: Round down to the start of the unit, or up to the start of the next one. Options: Round down, Round up. Default: Round down.
- **Custom Format · Optional**: Tokens: YYYY YY MMMM MMM MM DD dddd ddd HH hh mm ss A a Z ZZ (such as YYYY-MM-DD HH:mm). Other text is kept as written; put text in [brackets] to keep it whatever it says. Or a Go reference layout. A format that writes the year as yyyy, yy or y is read as a Luxon pattern instead: yyyy yy y MMMM MMM MM M dd d EEEE EEE HH H hh h mm m ss s SSS S a ZZZ ZZ Z (such as dd.MM.yyyy or yyyy-MM-dd'T'HH:mm:ss); put text in 'single quotes'. Shows when **Format** is **Custom format**.
- **To Unit · Optional**: The unit to round to, such as the start of the hour, day, or month. Options: Year, Month, Week (from Monday), Day, Hour, Minute, Second. Default: Month.
- **In Timezone · Optional**: Read the date in this IANA timezone (such as Europe/Berlin) before taking the part, period or rounding; a date written without an offset is a time in this zone. Blank = the date's own offset (UTC for a date without one).

### Convert timezone

- **Date · Required**: An ISO-8601 date/time (such as 2026-06-06T12:00:00Z), a unix timestamp, or an expression from an earlier step.
- **From Timezone · Optional**: The timezone the date is currently in, if it has no zone of its own (such as America/New_York). Default: UTC.
- **Custom Format · Optional**: Tokens: YYYY YY MMMM MMM MM DD dddd ddd HH hh mm ss A a Z ZZ (such as YYYY-MM-DD HH:mm). Other text is kept as written; put text in [brackets] to keep it whatever it says. Or a Go reference layout. A format that writes the year as yyyy, yy or y is read as a Luxon pattern instead: yyyy yy y MMMM MMM MM M dd d EEEE EEE HH H hh h mm m ss s SSS S a ZZZ ZZ Z (such as dd.MM.yyyy or yyyy-MM-dd'T'HH:mm:ss); put text in 'single quotes'. Shows when **Format** is **Custom format**.
- **To Timezone · Optional**: The timezone you want the date converted into (such as Europe/London). Default: UTC.

### Next weekday

- **Weekday · Optional**: The day of the week to find next, for example the next upcoming Friday. Options: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday. Default: Monday.
- **Custom Format · Optional**: Tokens: YYYY YY MMMM MMM MM DD dddd ddd HH hh mm ss A a Z ZZ (such as YYYY-MM-DD HH:mm). Other text is kept as written; put text in [brackets] to keep it whatever it says. Or a Go reference layout. A format that writes the year as yyyy, yy or y is read as a Luxon pattern instead: yyyy yy y MMMM MMM MM M dd d EEEE EEE HH H hh h mm m ss s SSS S a ZZZ ZZ Z (such as dd.MM.yyyy or yyyy-MM-dd'T'HH:mm:ss); put text in 'single quotes'. Shows when **Format** is **Custom format**.
- **Output Timezone · Optional**: IANA timezone for the output (such as America/New_York). For Next weekday, the zone whose calendar decides what today is. Default: UTC.

Source: https://docs.gorunner.io/apps/date-time