---
title: toTimeUnit
description: |
  Returns an interval converted to a numeric value in the requested time unit.

  Use `toTimeUnit` when you need an interval as a plain number, for example, to report a duration in seconds, plot it on a numeric chart, or compare it against a numeric threshold.
url: https://coralogix.com/docs/dataprime/language-reference/functions-reference/time/totimeunit/
product: dataengine
feature: DataPrime Language
feature_id: dataprime-language
feature_identifier: dataengine/dataprime-language
last_updated: '2026-10-21'
---

# `toTimeUnit`

## Description

Returns an interval converted to a numeric value in the requested time unit.

Use `toTimeUnit` when you need an interval as a plain number, for example, to report a duration in seconds, plot it on a numeric chart, or compare it against a numeric threshold.

## Syntax

Like many functions in DataPrime, `toTimeUnit` supports<!-- --> [two notations](https://coralogix.com/docs/dataprime/language-reference/functions-reference.md),<!-- --> **function** and **method**. These interchangeable forms allow flexibility in how you structure expressions.

* Function notation
* Method notation

```
toTimeUnit(interval: interval, timeUnit?: timeunit): number
```

```
(interval: interval).toTimeUnit(timeUnit?: timeunit): number
```

## Arguments

| Name       | Type       | Required  | Description                                 |
| ---------- | ---------- | --------- | ------------------------------------------- |
| `interval` | `interval` | **true**  | The interval to convert                     |
| `timeUnit` | `timeunit` | **false** | The unit for the result. Defaults to `nano` |

## Example 1

**Use case: Convert a literal interval to a numeric value**

Convert an interval expression directly into a number of the requested units. Useful as a building block inside larger expressions.

### Example query

* Function notation
* Method notation

```
choose toTimeUnit(2h30m, 'h') as hours
```

```
choose 2h30m.toTimeUnit('h') as hours
```

### Example output

```
{

  "hours": 2.5

}
```

## Example 2

**Use case: Report event age in seconds**

Compute how long ago an event occurred and convert it to a numeric value in seconds, suitable for thresholds, charts, or downstream systems that expect a plain number.

### Example query

* Function notation
* Method notation

```
choose toTimeUnit(now() - $m.timestamp, 's') as age_seconds
```

```
choose (now() - $m.timestamp).toTimeUnit('s') as age_seconds
```

### Example output

```
{

  "age_seconds": 300

}
```