> ## Documentation Index
> Fetch the complete documentation index at: https://axiom-support-improvements-2025-10-20.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Datetime functions

> Learn how to use and combine different timespan functions in APL

The table summarizes the datetime functions available in APL.

| Name                                                                                                            | Description                                                                                                          |
| --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| [ago](#ago)                                                                                                     | Subtracts the given timespan from the current UTC clock time.                                                        |
| [datetime\_add](#datetime-add)                                                                                  | Calculates a new datetime from a specified datepart multiplied by a specified amount, added to a specified datetime. |
| [datetime\_part](#datetime-part)                                                                                | Extracts the requested date part as an integer value.                                                                |
| [datetime\_diff](#datetime-diff)                                                                                | Calculates calendarian difference between two datetime values.                                                       |
| [dayofmonth](#dayofmonth)                                                                                       | Returns the integer number representing the day number of the given month                                            |
| [dayofweek](#dayofweek)                                                                                         | Returns the integer number of days since the preceding Sunday, as a timespan.                                        |
| [dayofyear](#dayofyear)                                                                                         | Returns the integer number represents the day number of the given year.                                              |
| [endofyear](#endofyear)                                                                                         | Returns the end of the year containing the date                                                                      |
| [getmonth](#getmonth)                                                                                           | Get the month number (1-12) from a datetime.                                                                         |
| [getyear](#getyear)                                                                                             | Returns the year part of the `datetime` argument.                                                                    |
| [hourofday](#hourofday)                                                                                         | Returns the integer number representing the hour number of the given date.                                           |
| [endofday](#endofday)                                                                                           | Returns the end of the day containing the date.                                                                      |
| [now](#now)                                                                                                     | Returns the current UTC clock time, optionally offset by a given timespan.                                           |
| [endofmonth](#endofmonth)                                                                                       | Returns the end of the month containing the date.                                                                    |
| [endofweek](#endofweek)                                                                                         | Returns the end of the week containing the date.                                                                     |
| [monthofyear](#monthofyear)                                                                                     | Returns the integer number represents the month number of the given year.                                            |
| [startofday](#startofday)                                                                                       | Returns the start of the day containing the date.                                                                    |
| [startofmonth](#startofmonth)                                                                                   | Returns the start of the month containing the date.                                                                  |
| [startofweek](#startofweek)                                                                                     | Returns the start of the week containing the date.                                                                   |
| [startofyear](#startofyear)                                                                                     | Returns the start of the year containing the date.                                                                   |
| [unixtime\_microseconds\_todatetime](/apl/scalar-functions/datetime-functions/unixtime-microseconds-todatetime) | Converts a Unix timestamp expressed in whole microseconds to an APL `datetime` value.                                |
| [unixtime\_milliseconds\_todatetime](/apl/scalar-functions/datetime-functions/unixtime-milliseconds-todatetime) | Converts a Unix timestamp expressed in whole milliseconds to an APL `datetime` value.                                |
| [unixtime\_nanoseconds\_todatetime](/apl/scalar-functions/datetime-functions/unixtime-nanoseconds-todatetime)   | Converts a Unix timestamp expressed in whole nanoseconds to an APL `datetime` value.                                 |
| [unixtime\_seconds\_todatetime](/apl/scalar-functions/datetime-functions/unixtime-seconds-todatetime)           | Converts a Unix timestamp expressed in whole seconds to an APL `datetime` value.                                     |
| [week\_of\_year](/apl/scalar-functions/datetime-functions/week-of-year)                                         | Returns the ISO 8601 week number from a datetime expression.                                                         |

Axiom supports the ISO 8601 format which is the standard format for representing dates and times in the Gregorian calendar. For more information, see [Supported formats](/apl/data-types/scalar-data-types#supported-formats).

## ago

Subtracts the given timespan from the current UTC clock time.

### Arguments

* Interval to subtract from the current UTC clock time

### Returns

now() - a\_timespan

### Example

```kusto theme={null}
ago(6h)
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20date_time_functions%20%3D%20ago%286h%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json theme={null}
{
  "date_time_functions": "2023-09-11T20:12:39Z"
}
```

```kusto theme={null}
ago(3d)
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20date_time_functions%20%3D%20ago%283d%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json theme={null}
{
  "date_time_functions": "2023-09-09T02:13:29Z"
}
```

## datetime\_add

Calculates a new datetime from a specified datepart multiplied by a specified amount, added to a specified datetime.

### Arguments

* period: string.
* amount: integer.
* datetime: datetime value.

### Returns

A date after a certain time/date interval has been added.

### Example

```kusto theme={null}
datetime_add(period,amount,datetime)
```

```kusto theme={null}
['sample-http-logs']
| project new_datetime = datetime_add( "month", 1, datetime(2016-10-06))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20new_datetime%20%3D%20datetime_add%28%20%5C%22month%5C%22%2C%201%2C%20datetime%282016-10-06%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json theme={null}
{
  "new_datetime": "2016-11-06T00:00:00Z"
}
```

## datetime\_part

Extracts the requested date part as an integer value.

### Arguments

* date: datetime
* part: string

### Returns

An integer representing the extracted part.

### Examples

```kusto theme={null}
datetime_part(part,datetime)
```

```kusto theme={null}
['sample-http-logs']
| project new_datetime = datetime_part("Day", datetime(2016-06-26T08:20:03.123456Z))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20new_datetime%20%3D%20datetime_part%28%5C%22Day%5C%22%2C%20datetime%282016-06-26T08%3A20%3A03.123456Z%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json theme={null}
{
  "new_datetime": 26
}
```

## datetime\_diff

Calculates calendarian difference between two datetime values.

### Arguments

* period: string.
* datetime\_1: datetime value.
* datetime\_2: datetime value.

### Returns

An integer, which represents amount of periods in the result of subtraction (datetime\_1 - datetime\_2).

### Example

```kusto theme={null}
datetime_diff(period,datetime_1,datetime_2)
```

```kusto theme={null}
['sample-http-logs']
| project new_datetime = datetime_diff("week", datetime(2019-06-26T08:20:03.123456Z), datetime(2014-06-26T08:19:03.123456Z))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20new_datetime%20%3D%20datetime_diff%28%5C%22week%5C%22%2C%20datetime%28%5C%222019-06-26T08%3A20%3A03.123456Z%5C%22%29%2C%20datetime%28%5C%222014-06-26T08%3A19%3A03.123456Z%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json theme={null}
{
  "new_datetime": 260
}
```

```kusto theme={null}
['sample-http-logs']
| project new_datetime = datetime_diff("week", datetime(2015-11-08), datetime(2014-11-08))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20new_datetime%20%3D%20datetime_diff%28%5C%22week%5C%22%2C%20datetime%28%5C%222014-11-08%5C%22%29%2C%20datetime%28%5C%222014-11-08%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json theme={null}
{
  "new_datetime": 52
}
```

## dayofmonth

Returns the integer number representing the day number of the given month

### Arguments

* `a_date`: A `datetime`

### Returns

day number of the given month.

### Example

```kusto theme={null}
dayofmonth(a_date)
```

```kusto theme={null}
['sample-http-logs']
| project day_of_the_month = dayofmonth(datetime(2017-11-30))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20day_of_the_month%20%3D%20dayofmonth%28datetime%28%5C%222017-11-30%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json theme={null}
{
  "day_of_the_month": 30
}
```

## dayofweek

Returns the integer number of days since the preceding Sunday, as a timespan.

### Arguments

* a\_date: A datetime.

### Returns

The `timespan` since midnight at the beginning of the preceding Sunday, rounded down to an integer number of days.

### Example

```kusto theme={null}
dayofweek(a_date)
```

```kusto theme={null}
['sample-http-logs']
| project day_of_the_week = dayofweek(datetime(2019-05-18))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20day_of_the_week%20%3D%20dayofweek%28datetime%28%5C%222019-05-18%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json theme={null}
{
  "day_of_the_week": 6
}
```

## dayofyear

Returns the integer number represents the day number of the given year.

### Arguments

* `a_date`: A `datetime.`

### Returns

`day number` of the given year.

### Example

```kusto theme={null}
dayofyear(a_date)
```

```kusto theme={null}
['sample-http-logs']
| project day_of_the_year = dayofyear(datetime(2020-07-20))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20day_of_the_year%20%3D%20dayofyear%28datetime%28%5C%222020-07-20%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json theme={null}
{
  "day_of_the_year": 202
}
```

## endofyear

Returns the end of the year containing the date

### Arguments

* date: The input date.

### Returns

A datetime representing the end of the year for the given date value

### Example

```kusto theme={null}
endofyear(date)
```

```kusto theme={null}
['sample-http-logs']
| extend end_of_the_year = endofyear(datetime(2016-06-26T08:20))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20%20end_of_the_year%20%3D%20endofyear%28datetime%28%5C%222016-06-26T08%3A20%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json theme={null}
{
  "end_of_the_year": "2016-12-31T23:59:59.999999999Z"
}
```

## getmonth

Get the month number (1-12) from a datetime.

```kusto theme={null}
['sample-http-logs']
| extend get_specific_month = getmonth(datetime(2020-07-26T08:20))
```

## getyear

Returns the year part of the `datetime` argument.

### Example

```kusto theme={null}
getyear(datetime())
```

```kusto theme={null}
['sample-http-logs']
| project get_specific_year = getyear(datetime(2020-07-26))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20get_specific_year%20%3D%20getyear%28datetime%28%5C%222020-07-26%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json theme={null}
{
  "get_specific_year": 2020
}
```

## hourofday

Returns the integer number representing the hour number of the given date

### Arguments

* a\_date: A datetime.

### Returns

hour number of the day (0-23).

### Example

```kusto theme={null}
hourofday(a_date)
```

```kusto theme={null}
['sample-http-logs']
| project get_specific_hour = hourofday(datetime(2016-06-26T08:20:03.123456Z))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20get_specific_hour%20%3D%20hourofday%28datetime%28%5C%222016-06-26T08%3A20%3A03.123456Z%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json theme={null}
{
  "get_specific_hour": 8
}
```

## endofday

Returns the end of the day containing the date

### Arguments

* date: The input date.

### Returns

A datetime representing the end of the day for the given date value.

### Example

```kusto theme={null}
endofday(date)
```

```kusto theme={null}
['sample-http-logs']
| project end_of_day_series = endofday(datetime(2016-06-26T08:20:03.123456Z))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20end_of_day_series%20%3D%20endofday%28datetime%28%5C%222016-06-26T08%3A20%3A03.123456Z%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json theme={null}
{
  "end_of_day_series": "2016-06-26T23:59:59.999999999Z"
}
```

## now

Returns the current UTC clock time, optionally offset by a given timespan. This function can be used multiple times in a statement and the clock time being referenced will be the same for all instances.

### Arguments

* offset: A timespan, added to the current UTC clock time. Default: 0.

### Returns

The current UTC clock time as a datetime.

### Example

```kusto theme={null}
now([offset])
```

```kusto theme={null}
['sample-http-logs']
| project returns_clock_time = now(-5d)
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20returns_clock_time%20%3D%20now%28-5d%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json theme={null}
{
  "returns_clock_time": "2023-09-07T02:54:50Z"
}
```

## endofmonth

Returns the end of the month containing the date

### Arguments

* date: The input date.

### Returns

A datetime representing the end of the month for the given date value.

### Example

```kusto theme={null}
endofmonth(date)
```

```kusto theme={null}
['sample-http-logs']
| project end_of_the_month = endofmonth(datetime(2016-06-26T08:20))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20end_of_the_month%20%3D%20endofmonth%28datetime%28%5C%222016-06-26T08%3A20%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json theme={null}
{
  "end_of_the_month": "2016-06-30T23:59:59.999999999Z"
}
```

## endofweek

Returns the end of the week containing the date

### Arguments

* date: The input date.

### Returns

A datetime representing the end of the week for the given date value

### Example

```kusto theme={null}
endofweek(date)
```

```kusto theme={null}
['sample-http-logs']
| project end_of_the_week = endofweek(datetime(2019-04-18T08:20))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20end_of_the_week%20%3D%20endofweek%28datetime%28%5C%222019-04-18T08%3A20%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json theme={null}
{
  "end_of_the_week": "2019-04-20T23:59:59.999999999Z"
}
```

## monthofyear

Returns the integer number represents the month number of the given year.

### Arguments

* `date`: A datetime.

### Returns

month number of the given year.

### Example

```kusto theme={null}
monthofyear(datetime("2018-11-21"))
```

```kusto theme={null}
['sample-http-logs']
| project month_of_the_year = monthofyear(datetime(2018-11-11))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20month_of_the_year%20%3D%20monthofyear%28datetime%28%5C%222018-11-11%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json theme={null}
{
  "month_of_the_year": 11
}
```

## startofday

Returns the start of the day containing the date

### Arguments

* date: The input date.

### Returns

A datetime representing the start of the day for the given date value

### Examples

```kusto theme={null}
startofday(datetime(2020-08-31))
```

```kusto theme={null}
['sample-http-logs']
| project start_of_the_day = startofday(datetime(2018-11-11))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20start_of_the_day%20%3D%20startofday%28datetime%28%5C%222018-11-11%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json theme={null}
{
  "start_of_the_day": "2018-11-11T00:00:00Z"
}
```

## startofmonth

Returns the start of the month containing the date

### Arguments

* date: The input date.

### Returns

A datetime representing the start of the month for the given date value

### Example

```kusto theme={null}
['github-issues-event']
| project start_of_the_month =  startofmonth(datetime(2020-08-01))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27github-issues-event%27%5D%5Cn%7C%20project%20start_of_the_month%20%3D%20%20startofmonth%28datetime%28%5C%222020-08-01%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json theme={null}
{
  "start_of_the_month": "2020-08-01T00:00:00Z"
}
```

```kusto theme={null}
['hackernews']
| extend start_of_the_month = startofmonth(datetime(2020-08-01))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27hn%27%5D%5Cn%7C%20project%20start_of_the_month%20%3D%20startofmonth%28datetime%28%5C%222020-08-01%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json theme={null}
{
  "start_of_the_month": "2020-08-01T00:00:00Z"
}
```

## startofweek

Returns the start of the week containing the date

Start of the week is considered to be a Sunday.

### Arguments

* date: The input date.

### Returns

A datetime representing the start of the week for the given date value

### Examples

```kusto theme={null}
['github-issues-event']
| extend start_of_the_week =  startofweek(datetime(2020-08-01))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27github-issues-event%27%5D%5Cn%7C%20project%20start_of_the_week%20%3D%20%20startofweek%28datetime%28%5C%222020-08-01%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json theme={null}
{
  "start_of_the_week": "2020-07-26T00:00:00Z"
}
```

```kusto theme={null}
['hackernews']
| extend start_of_the_week = startofweek(datetime(2020-08-01))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27hn%27%5D%5Cn%7C%20project%20start_of_the_week%20%3D%20startofweek%28datetime%28%5C%222020-08-01%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json theme={null}
{
  "start_of_the_week": "2020-07-26T00:00:00Z"
}
```

```kusto theme={null}
['sample-http-logs']
| extend start_of_the_week = startofweek(datetime(2018-06-11T00:00:00Z))
```

## startofyear

Returns the start of the year containing the date

### Arguments

* date: The input date.

### Returns

A datetime representing the start of the year for the given date value

### Examples

```kusto theme={null}
['sample-http-logs']
| project yearStart = startofyear(datetime(2019-04-03))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20yearStart%20%3D%20startofyear%28datetime%28%5C%222019-04-03%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json theme={null}
{
  "yearStart": "2019-01-01T00:00:00Z"
}
```

```kusto theme={null}
['sample-http-logs']
| project yearStart = startofyear(datetime(2019-10-09 01:00:00.0000000))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20yearStart%20%3D%20startofyear%28datetime%28%5C%222019-10-09%2001%3A00%3A00.0000000%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json theme={null}
{
  "yearStart": "2019-01-01T00:00:00Z"
}
```