---
title: stateDuration() function
description: The `stateDuration()` function computes the duration of a given state.
aliases:
  - /influxdb/v2.0/reference/flux/functions/transformations/stateduration
  - /influxdb/v2.0/reference/flux/functions/built-in/transformations/stateduration/
  - /influxdb/v2.0/reference/flux/stdlib/built-in/transformations/stateduration/
  - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/stateduration/
menu:
  flux_0_x_ref:
    name: stateDuration
    parent: universe
weight: 102
flux/v0.x/tags: [transformations]
related:
  - /{{< latest "influxdb" >}}/query-data/flux/monitor-states/
  - /flux/v0.x/stdlib/contrib/tomhollingworth/events/duration/
introduced: 0.7.0
---

`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.
{{% /note %}}

```js
stateDuration(fn: (r) => r._measurement == "state", column: "stateDuration", unit: 1s)
```

_If the expression generates an error during evaluation, the point is discarded,
and does not affect the state duration._

## Parameters

{{% note %}}
Make sure `fn` parameter names match each specified parameter. To learn why, see [Match parameter names](/flux/v0.x/spec/data-model/#match-parameter-names).
{{% /note %}}

### fn {data-type="function"}
({{< req >}})
A single argument function that evaluates true or false to identify the state of the record.
Records are passed to the function.
Those that evaluate to `true` increment the state duration.
Those that evaluate to `false` reset the state duration.

### column {data-type="string"}
Name of the column added to each record that contains the state duration.
Default is `stateDuration`.

### unit {data-type="duration"}

Unit of time to increment state duration with.
For example: `1s`, `1m`, `1h`, etc.
Default is one second (`1s`).

### tables {data-type="stream of tables"}
Input data.
Default is piped-forward data ([`<-`](/flux/v0.x/spec/expressions/#pipe-expressions)).

## Examples
{{% flux/sample-example-intro %}}

```js
import "sampledata"

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

{{< expand-wrapper >}}
{{% expand "View input and output" %}}
{{< flex >}}
{{% flex-content %}}

##### Input data
{{% flux/sample "int" %}}

{{% /flex-content %}}
{{% flex-content %}}

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

| _time                | tag | _value | stateDuration |
| :------------------- | :-- | -----: | ------------: |
| 2021-01-01T00:00:00Z | t2  |     19 |             0 |
| 2021-01-01T00:00:10Z | t2  |      4 |            -1 |
| 2021-01-01T00:00:20Z | t2  |     -3 |            -1 |
| 2021-01-01T00:00:30Z | t2  |     19 |             0 |
| 2021-01-01T00:00:40Z | t2  |     13 |            10 |
| 2021-01-01T00:00:50Z | t2  |      1 |            -1 |
{{% /flex-content %}}
{{< /flex >}}
{{% /expand %}}
{{< /expand-wrapper >}}