# `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/index.md), **function** and **method** notation. These interchangeable forms allow flexibility in how you structure expressions.

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

```dataprime
(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

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

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

### Example output

```json
{
  "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

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

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

### Example output

```json
{
  "age_seconds": 300
}
```