<!-- BusyBot node reference — https://busybot.net/tools/date-time/ -->

> Node: Date & Time (`date_time`) · Action · v1
> Category: Core Nodes · Credentials: none
> Updated: 2026-08-16

# Date & Time

> Manipulate date and time values

## Overview

The Date & Time tool provides 7 date/time operations: getCurrentDate, addToDate, subtractFromDate, formatDate, roundDate, getTimeBetweenDates, and extractDate. Date handling is timezone-aware. Supports multiple input formats including ISO strings, Unix timestamps (seconds/milliseconds), and custom format strings.

**Category:** Core Nodes  
**Tool Name:** `date_time`  
**Version:** 1

**Appearance:** Icon: `lucide-Calendar` | Color: `#408000`

## Node Type

**Action** — processes input items and produces output

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool does not require any credentials.

### Operations

| Operation | Value | Description |
|-----------|-------|-------------|
| Add to a Date | `addToDate` | Move a date forward by a number of time units |
| Extract Part of a Date | `extractDate` | Read a single component, such as the month, out of a date |
| Format a Date | `formatDate` | Render a date as a string in a chosen format |
| Get Current Date | `getCurrentDate` | Produce the current date and time |
| Get Time Between Dates | `getTimeBetweenDates` | Measure the gap between two dates |
| Round a Date | `roundDate` | Snap a date to the start or end of a unit |
| Subtract From a Date | `subtractFromDate` | Move a date backward by a number of time units |

### Parameters

#### Add to a Date (`addToDate`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Date (`magnitude`) | `string` | Yes | — | The date to add to. Accepts ISO strings, timestamps, or date expressions. |
| Time Unit | `options` | No | `days` | The time unit for the duration. |
| | | | | Options: `years`, `quarters`, `months`, `weeks`, `days`, `hours`, `minutes`, `seconds`, `milliseconds` |
| Duration | `number` | No | `0` | The number of time units to add or subtract. |
| Output Field Name | `string` | No | `newDate` | Name of the output field. |

#### Extract Part of a Date (`extractDate`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Date (`date`) | `string` | Yes | — | The date to extract from. |
| Part | `options` | No | `month` | The part of the date to extract. |
| | | | | Options: `year`, `month`, `week` (ISO week number), `day`, `hour`, `minute`, `second` |
| Output Field Name | `string` | No | `datePart` | Name of the output field. |

#### Format a Date (`formatDate`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Date (`date`) | `string` | Yes | — | The date to format. |
| Format | `options` | No | `MM/dd/yyyy` | The format to output the date in. |
| | | | | Options: `MM/dd/yyyy`, `yyyy/MM/dd`, `MMMM dd yyyy`, `MM-dd-yyyy`, `yyyy-MM-dd`, `X` (Unix timestamp in seconds), `x` (Unix timestamp in milliseconds), `custom` |
| Custom Format | `string` | No | — | The custom Luxon format string. _(shown when Format is `custom`)_ |
| Output Field Name | `string` | No | `formattedDate` | Name of the output field. |

#### Get Current Date (`getCurrentDate`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Include Time | `boolean` | No | `true` | Whether to include the time in the output or just the date (midnight). |
| Output Field Name | `string` | No | `currentDate` | Name of the output field to put the date value in. |

#### Get Time Between Dates (`getTimeBetweenDates`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Start Date | `string` | Yes | — | The start date. |
| End Date | `string` | Yes | — | The end date. |
| Units | `multiOptions` | No | `["days"]` | The units to calculate the difference in. Select more than one to split the gap across them. |
| | | | | Options: `years`, `months`, `weeks`, `days`, `hours`, `minutes`, `seconds`, `milliseconds` |
| Output Field Name | `string` | No | `timeDifference` | Name of the output field. |

#### Round a Date (`roundDate`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Date (`date`) | `string` | Yes | — | The date to round. |
| Mode | `options` | No | `roundDown` | Whether to round down (start of) or round up (end of + 1). |
| | | | | Options: `roundDown`, `roundUp` |
| To Nearest | `options` | No | `day` | The unit to round down to. _(shown when Mode is `roundDown`)_ |
| | | | | Options: `year`, `month`, `week`, `day`, `hour`, `minute`, `second` |
| To | `options` | No | `month` | The unit to round up to. _(shown when Mode is `roundUp`)_ |
| | | | | Options: `month` (end of month) |
| Output Field Name | `string` | No | `roundedDate` | Name of the output field. |

#### Subtract From a Date (`subtractFromDate`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Date (`magnitude`) | `string` | Yes | — | The date to subtract from. |
| Time Unit | `options` | No | `days` | The time unit for the duration. |
| | | | | Options: `years`, `quarters`, `months`, `weeks`, `days`, `hours`, `minutes`, `seconds`, `milliseconds` |
| Duration | `number` | No | `0` | The number of time units to add or subtract. |
| Output Field Name | `string` | No | `newDate` | Name of the output field. |

#### All Operations

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Options | `collection` | No | `{}` | Shared parsing and output settings. |
| — Include Input Fields | `boolean` | No | `false` | Whether to include all input fields in the output alongside the result. |
| — Timezone | `string` | No | — | The timezone to use. If not set, UTC is used. |
| — From Format | `string` | No | — | The Luxon format string of the input date (helps with parsing non-standard formats). _(shown when Operation is `formatDate`)_ |
| — Output as ISO String | `boolean` | No | `false` | Whether to output the duration as an ISO 8601 duration string instead of an object. _(shown when Operation is `getTimeBetweenDates`)_ |
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. |

## Output Data

One output item per input item. Binary data is forwarded.

**The output item starts empty.** By default only the result field is present — the rest of the input JSON is dropped. Turn on **Include Input Fields** to copy the incoming fields through and add the result beside them. The result is written at **Output Field Name**, or at `result` if you clear that field.

| Operation | Type of the result value |
|-----------|--------------------------|
| `getCurrentDate` | ISO 8601 string. With **Include Time** off, the time is midnight at the start of today. |
| `addToDate`, `subtractFromDate` | ISO 8601 string of the shifted date. |
| `formatDate` | String in the chosen **Format**. `X` and `x` give the Unix timestamp in seconds and milliseconds. An empty input date yields `null` rather than an error. |
| `roundDate` | ISO 8601 string. `roundDown` snaps to the start of **To Nearest**; `roundUp` moves to the start of the next **To** unit. |
| `getTimeBetweenDates` | An object with one key per selected unit, or an ISO 8601 duration string when **Output as ISO String** is on. |
| `extractDate` | A number — the requested component. `week` gives the ISO week number. |

With **Include Input Fields** on, a `getTimeBetweenDates` result looks like this:

```json
{
  "startTime": "2024-01-01T00:00:00Z",
  "endTime": "2024-01-15T12:00:00Z",
  "timeDifference": {
    "days": 14,
    "hours": 12
  }
}
```

Reference the result downstream by expression, e.g. `{{ $json.timeDifference.days }}`.

Dates are read flexibly: ISO 8601 strings, Unix timestamps in seconds or milliseconds, and anything standard date parsing accepts. Set **From Format** when the input uses a layout that is ambiguous, such as `dd/MM/yyyy`. A value that cannot be parsed at all fails the item.

All operations work in UTC unless you set **Timezone**, which takes an IANA name such as `America/New_York`.

## Usage Examples

- Format a date to MM/DD/YYYY
- Add 7 days to a date field
- Get time between two dates in hours
- Extract the month from a timestamp

## Example Configuration

Get the current date and time in a specific timezone:

```json
{
  "type": "date_time",
  "parameters": {
    "operation": "getCurrentDate",
    "includeTime": true,
    "outputFieldName": "currentDateTime",
    "options": {
      "includeInputFields": false,
      "timezone": "America/New_York"
    }
  }
}
```

Add seven days to a date, keeping the original fields:

```json
{
  "type": "date_time",
  "parameters": {
    "operation": "addToDate",
    "magnitude": "2024-01-15T10:30:00Z",
    "timeUnit": "days",
    "duration": 7,
    "outputFieldName": "futureDate",
    "options": {
      "includeInputFields": true,
      "timezone": "UTC"
    }
  }
}
```

Format a date with a custom pattern:

```json
{
  "type": "date_time",
  "parameters": {
    "operation": "formatDate",
    "date": "2024-01-15T10:30:00Z",
    "format": "custom",
    "customFormat": "yyyy-MM-dd HH:mm:ss",
    "outputFieldName": "formattedDate",
    "options": {
      "includeInputFields": false,
      "timezone": "America/Los_Angeles"
    }
  }
}
```

Round a timestamp down to the start of its day:

```json
{
  "type": "date_time",
  "parameters": {
    "operation": "roundDate",
    "date": "2024-01-15T14:30:45Z",
    "mode": "roundDown",
    "toNearest": "day",
    "outputFieldName": "roundedDate"
  }
}
```

Measure a gap in days and hours:

```json
{
  "type": "date_time",
  "parameters": {
    "operation": "getTimeBetweenDates",
    "startDate": "2024-01-01T00:00:00Z",
    "endDate": "2024-01-15T12:00:00Z",
    "units": ["days", "hours"],
    "outputFieldName": "timeDifference",
    "options": {
      "includeInputFields": true,
      "timezone": "UTC"
    }
  }
}
```

Pull the month number out of a timestamp:

```json
{
  "type": "date_time",
  "parameters": {
    "operation": "extractDate",
    "date": "2024-01-15T14:30:45Z",
    "part": "month",
    "outputFieldName": "monthValue",
    "options": {
      "includeInputFields": false
    }
  }
}
```

Format a date taken from the incoming item:

```json
{
  "type": "date_time",
  "parameters": {
    "operation": "formatDate",
    "date": "{{ $json.timestamp }}",
    "format": "MM/dd/yyyy",
    "outputFieldName": "displayDate"
  }
}
```

Calculate an expiry six months out:

```json
{
  "type": "date_time",
  "parameters": {
    "operation": "addToDate",
    "magnitude": "{{ $json.createdAt }}",
    "timeUnit": "months",
    "duration": 6,
    "outputFieldName": "expiresAt"
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Manipulate dates: format, add/subtract, compare, round, extract parts — uses Luxon for timezone-aware operations.

### Common Patterns

- **Basic date formatting** — use `formatDate` with one of the predefined formats for common date representations.
- **Date arithmetic** — use `addToDate` or `subtractFromDate` for scheduling and expiration calculations.
- **Timezone conversion** — set **Timezone** in Options to render a UTC value in a local zone.
- **Date range calculations** — use `getTimeBetweenDates` with the units your report needs, such as hours and minutes.

### Notes

- Turn **Include Input Fields** on whenever a downstream node still needs the rest of the item; otherwise the result field is all that survives.
- `formatDate` only applies **Timezone** when you set it — leave it empty to format the date exactly as parsed.