Date Operators & Helpers

Beeceptor's template engine provides date manipulation operators to generate dynamic date-time values for API responses. The engine supports current time retrieval, relative time calculations, and customizable date formatting using standard formats like ISO, UTC, Unix timestamps, and custom patterns. These operators can be used within response templates using the {{now}} syntax with optional formatting parameters.

now - current time

The now operator allows you to retrieve the current date and time. Additionally, you can customize the format of the date-time output by passing a shorthand format parameter.

Syntax	Description & Sample Output
{{now}}	Current date-time, in long format Thu Oct 10 2024 04:39:51 GMT+0000 (Coordinated Universal Time)
{{now 'utc'}}	Current date-time in UTC format 2024-10-10T04:39:51Z
{{now 'iso'}}	Current date-time in ISO format 2024-10-10T04:39:51.000+00:00

now - relative time

You can create custom date-time values relative to the current time by using additional parameters that specify the duration. For example, you can set the time to be 5 minutes in the future or 1 hour in the past. The duration can be defined in seconds, minutes, hours, days, months, or years, and it accepts both positive and negative whole numbers.

This feature is particularly useful when you need an API response that always returns a recent or dynamically adjusted date whenever the API is called. Below are some examples to help you customize date-time values:

Syntax	Description & Sample Output
{{now '{minutes:5}' 'utc'}}	Date-time exactly 5 minutes in the future 2024-10-10T04:44:51Z
{{now '{months:-11, days:1}' 'iso'}}	Date-time exactly 11 months in the past 2023-11-11T04:39:51.000+00:00
{{now '{hours:-5, minutes:-30}' 'YYYYMMDD'}}	Date with timezone adjustments 20241009
{{now '{hours:3}' 'utc'}}	Date-time 3 hours in the future (in UTC) 2024-10-10T07:39:51Z
{{now '{days: 1, hours:10}' 'utc'}}	Date-time 1 day and 3 hours in the future (in UTC) 2024-10-10T07:39:51Z

Note: The last parameter here is optional, and controls the output format. Refer date/time formatting for more details.

Date Formatting

When working with mock APIs, you might need to generate date values in a particular format. Beeceptor supports a range of date formatting options, enabling you to customize both standard and non-standard date outputs to suit your requirements.

Examples

You can generate date values using the following syntax with for a variety of formats. Below are some common examples:

Use Case	Template's Syntax	Template's Output
Future Date in ISO Format	{{faker 'date.future' 'iso'}}	2024-03-22T14:12:53.789+00:00
Recent Date in UTC Format	{{faker 'date.recent' 'utc'}}	2024-10-03T10:22:45Z
Future Timestamp in Milliseconds	{{faker 'date.future' 'timestamp'}}	1734963456000
Past Date in US Format	{{faker 'date.past' 'us'}}	12/15/2021
Custom Date Format (ISO with Milliseconds)	{{faker 'date.past' 'YYYY-MM-DDTHH:mm:ss.SSSZ'}}	2022-04-10T05:32:21.456+00:00
Time Only in Custom Format	{{faker 'date.past' 'HH:mm:ss.SSSZ'}}	11:45:32.123+00:00
Past Date in European Format	{{faker 'date.past' 'eu'}}	15/12/2021
Full Human-readable Date Format	{{faker 'date.past' 'full'}}	Wednesday, April 10, 2022 5:32:21 AM
Compact Date Format for Unique ID	{{faker 'date.past' 'compact'}}	20220410053221
SQL Compatible Format	{{faker 'date.past' 'sql'}}	2022-04-10 05:32:21

The examples above illustrate how to specify different formats using the faker function to meet your specific requirements.

Shorthand Syntax

Beeceptor supports several shorthand notations for date formatting. The table below shows these standard notations and their corresponding formats:

Shorthand	Format Specification	Description
iso	YYYY-MM-DDTHH:mm:ss.SSSZ	ISO 8601 format with milliseconds; useful for international standards.
iso8601	YYYY-MM-DDTHH:mm:ss.SSSZ	Another alias for ISO 8601, commonly used in APIs.
rfc2822	ddd, DD MMM YYYY HH:mm:ss ZZ	RFC 2822 format, often used for email headers.
rfc3339	YYYY-MM-DDTHH:mm:ssZ	RFC 3339 format, suitable for machine-readable timestamps.
w3c	YYYY-MM-DDTHH:mm:ssZ	W3C standard for date and time on the web.
unix	X	Unix epoch time in seconds, useful for Unix-based systems.
timestamp	x	Unix epoch time in milliseconds; great for precise timestamps.
short	YYYY-MM-DD	Short date format, ideal for compact displays of date only.
long	YYYY-MM-DD HH:mm:ss	Long format with time, typically used for detailed logs.
full	dddd, MMMM D, YYYY h:mm:ss A	Full, human-readable date format; great for user interfaces.
compact	YYYYMMDDHHmmss	Compact representation with no separators; useful for IDs.
utc	YYYY-MM-DD[T]HH:mm:ss[Z]	UTC format, recommended for data that needs universal reference.
sql	YYYY-MM-DD HH:mm:ss	SQL-compatible format for database entries.
us	MM/DD/YYYY	US date format, typically used in US-based applications.
eu	DD/MM/YYYY	European date format, commonly used across Europe.