---
title: stateDuration() function
description: stateDuration() returns the cumulative duration of a given state.
url: https://docs.influxdata.com/flux/v0/stdlib/universe/stateduration/
estimated_tokens: 1900
product: Flux
version: v0
---

# stateDuration() function

-   Flux 0.7.0+
-   View InfluxDB support

`stateDuration()` returns the cumulative duration of a given state.

The state is defined by the `fn` predicate function. For each consecutive record that evaluates to `true`, the state duration is incremented by the duration of time between records using the specified `unit`. When a record evaluates to `false`, the value is set to `-1` and the state duration is reset. If the record generates an error during evaluation, the point is discarded, and does not affect the state duration.

The state duration is added as an additional column to each record. The duration is represented as an integer in the units specified.

**Note:** As the first point in the given state has no previous point, its state duration will be 0.

##### Function type signature

```js
(
    <-tables: stream[A],
    fn: (r: A) => bool,
    ?column: string,
    ?timeColumn: string,
    ?unit: duration,
) => stream[B] where A: Record, B: Record
```

For more information, see [Function type signatures](/flux/v0/function-type-signatures/).

## Parameters

### fn

(Required) Predicate function that identifies the state of a record.

### column

Column to store the state duration in. Default is `stateDuration`.

### timeColumn

Time column to use to calculate elapsed time between rows. Default is `_time`.

### unit

Unit of time to use to increment state duration. Default is `1s` (seconds).

**Example units:**

-   1ns (nanoseconds)
-   1us (microseconds)
-   1ms (milliseconds)
-   1s (seconds)
-   1m (minutes)
-   1h (hours)
-   1d (days)

### tables

Input data. Default is piped-forward data (`<-`).

## Examples

### Return the time spent in a specified state

```js
import "sampledata"

sampledata.int()
    |> stateDuration(fn: (r) => r._value < 15)
```

[](#view-example-input-and-output)

View example input and output

#### Input data

| _time | _value | *tag |
| --- | --- | --- |
| 2021-01-01T00:00:00Z | -2 | t1 |
| 2021-01-01T00:00:10Z | 10 | t1 |
| 2021-01-01T00:00:20Z | 7 | t1 |
| 2021-01-01T00:00:30Z | 17 | t1 |
| 2021-01-01T00:00:40Z | 15 | t1 |
| 2021-01-01T00:00:50Z | 4 | t1 |

| _time | _value | *tag |
| --- | --- | --- |
| 2021-01-01T00:00:00Z | 19 | t2 |
| 2021-01-01T00:00:10Z | 4 | t2 |
| 2021-01-01T00:00:20Z | -3 | t2 |
| 2021-01-01T00:00:30Z | 19 | t2 |
| 2021-01-01T00:00:40Z | 13 | t2 |
| 2021-01-01T00:00:50Z | 1 | t2 |

#### Output data

| _time | _value | *tag | stateDuration |
| --- | --- | --- | --- |
| 2021-01-01T00:00:00Z | -2 | t1 | 0 |
| 2021-01-01T00:00:10Z | 10 | t1 | 10 |
| 2021-01-01T00:00:20Z | 7 | t1 | 20 |
| 2021-01-01T00:00:30Z | 17 | t1 | -1 |
| 2021-01-01T00:00:40Z | 15 | t1 | -1 |
| 2021-01-01T00:00:50Z | 4 | t1 | 0 |

| _time | _value | *tag | stateDuration |
| --- | --- | --- | --- |
| 2021-01-01T00:00:00Z | 19 | t2 | -1 |
| 2021-01-01T00:00:10Z | 4 | t2 | 0 |
| 2021-01-01T00:00:20Z | -3 | t2 | 10 |
| 2021-01-01T00:00:30Z | 19 | t2 | -1 |
| 2021-01-01T00:00:40Z | 13 | t2 | 0 |
| 2021-01-01T00:00:50Z | 1 | t2 | 10 |

#### Related

-   [Monitor states](/influxdb/v2/query-data/flux/monitor-states/)
-   [events.duration() function](/flux/v0/stdlib/contrib/tomhollingworth/events/duration/)

[transformations](/flux/v0/tags/transformations/)