Skip to main content
The features described in this section are currently in private beta. For more information and to sign up, contact your Cognite representative.
State time series are a specialized time series type designed for tracking discrete operational states of industrial equipment. Unlike numeric or string time series, state time series have predefined valid states and support specialized aggregations optimized for analyzing state changes over time. States represent the discrete operational conditions of equipment at any point in time. They provide an unambiguous way to track, query, and analyze the operational state of equipment by managing machine states as a native element of time series data. Some common use cases for state time series include:
  • Equipment states: ON/OFF, OPEN/CLOSED, IDLE/RUNNING/ERROR/MAINTENANCE
  • Process states: HEATING/COOLING/STABLE, WARMING_UP/ACTIVE/STANDBY/COOLING_DOWN/OFF
  • Network equipment: UP/DOWN/DISABLE/ERROR
  • Environmental conditions: SUNNY/OVERCAST/NIGHT (for solar panels), CLEAR/RAINY/SNOWY (for weather stations)
  • Quality grades: A/B/C/D/E/F, PASS/FAIL, EXCELLENT/GOOD/FAIR/POOR

​
Core concepts

Understanding state time series requires familiarity with how they differ from numeric and string time series, how state sets define valid states, and how state transitions are tracked over time.

​
State vs. other time series types

AspectNumericStringState
ValuesContinuous measurementsFree-form textPredefined state set
Value validationNoneNoneValidated against state set
Aggregationsmin/max/avg/sumNot supportedduration/transitions/count per state
Typical use caseSensor measurementsLabels/commentsEquipment operational states
VisualizationLine/scatter chartsNot plottedStep charts with state labels

​
State sets

A state set is a named collection of valid state value pairs (integer, string) that defines the possible states for a time series. State sets are managed through the data modeling API and enable:
  • Shared definitions: Multiple time series can reference the same state set.
  • Validation: Data points are validated against the state set during ingestion.
  • Meaningful labels: Numeric state codes are automatically mapped to human-readable strings.
Example state set
{
  "name": "Standard Pump States",
  "states": [
    {
      "numericValue": 0,
      "stringValue": "OFF",
      "description": "Pump is powered off"
    },
    {
      "numericValue": 1,
      "stringValue": "RUNNING",
      "description": "Pump is actively operating"
    },
    {
      "numericValue": 2,
      "stringValue": "STANDBY",
      "description": "Pump is ready but not running"
    },
    {
      "numericValue": 3,
      "stringValue": "ERROR",
      "description": "Pump has encountered an error"
    }
  ]
}
Each state can optionally include a description field. Descriptions are stored in the data modeling service and are not returned by the time series API.

​
State constraints

State sets have the following constraints:
  • Maximum 100 unique states per state set. Fewer states present in aggregate periods result in smaller response payloads and faster retrieval.
  • Numeric values must be 32-bit integers (-2,147,483,648 to 2,147,483,647).
  • String values must be up to 255 UTF-8 characters.
  • Both numeric and string values must be unique within a state set.

​
State transitions

A state transition occurs when equipment changes from one state to another. During aggregation, the system tracks the number of transitions into each state. To retrieve the exact timestamps when state changes occurred or to determine which state the equipment transitioned from, fetch the raw data points directly.

​
API usage

State time series are created and managed through the data modeling API, while data ingestion and retrieval use the time series API. The following examples demonstrate how to work with state time series and state sets.

​
Create state time series

State time series can only be created through data modeling by setting the type property to state and linking to a state set: 
POST /api/v1/projects/{project}/models/instances
Content-Type: application/json

{
  "items": [{
    "space": "industrial_assets",
    "externalId": "valve_001_state",
    "instanceType": "node",
    "sources": [{
      "source": {
        "type": "view",
        "space": "cdf_cdm",
        "externalId": "CogniteTimeSeries",
        "version": "v1"
      },
      "properties": {
        "name": "Valve 001 Position",
        "type": "state",
        "stateSet": {
          "space": "state_definitions",
          "externalId": "valve_states"
        }
      }
    }]
  }]
}

​
Create state sets

State sets are created through data modeling using the CogniteStateSet view: 
POST /api/v1/projects/{project}/models/instances
Content-Type: application/json

{
  "items": [{
    "space": "state_definitions",
    "externalId": "valve_states",
    "instanceType": "node",
    "sources": [{
      "source": {
        "type": "view",
        "space": "cdf_cdm",
        "externalId": "CogniteStateSet",
        "version": "v1"
      },
      "properties": {
        "name": "Valve Position States",
        "description": "Standard position states for industrial valves",
        "states": [
          {"numericValue": 0, "stringValue": "CLOSED"},
          {"numericValue": 1, "stringValue": "OPEN"},
          {"numericValue": 2, "stringValue": "TRANSITIONING"}
        ]
      }
    }]
  }]
}

​
Ingest state data

State data points can include both numeric and string values. If both are provided, they must correspond to the same state: 
POST /api/v1/projects/{project}/timeseries/data
Content-Type: application/json

{
  "items": [{
    "instanceId": {"space": "industrial_assets", "externalId": "valve_001_state"},
    "datapoints": [
      {
        "timestamp": 1609459200000,
        "numericValue": 0,
        "stringValue": "CLOSED"
      },
      {
        "timestamp": 1609462800000,
        "numericValue": 1,
        "stringValue": "OPEN"
      },
      {
        "timestamp": 1609466400000,
        "numericValue": 0,
        "stringValue": "CLOSED"
      }
    ]
  }]
}

​
Retrieve raw data points

When retrieving raw data points, the numericValue is returned if present. For data points with a Bad status, the numericValue may be null or omitted. If the numeric value exists in the current state set, the response also includes the stringValue: 
POST /api/v1/projects/{project}/timeseries/data/list
Content-Type: application/json

{
  "items": [{
    "instanceId": {"space": "industrial_assets", "externalId": "valve_001_state"},
    "limit": 10,
    "start": 1609459200000,
    "end": 1609545600000
  }]
}
Response:
{
  "items": [{
    "instanceId": {"space": "industrial_assets", "externalId": "valve_001_state"},
    "type": "state",
    "stateSet": {
      "space": "state_definitions",
      "externalId": "valve_states"
    },
    "datapoints": [
      {
        "timestamp": 1609459200000,
        "numericValue": 0,
        "stringValue": "CLOSED"
      },
      {
        "timestamp": 1609462800000,
        "numericValue": 1,
        "stringValue": "OPEN"
      }
    ]
  }]
}

​
Retrieve state aggregations

State time series support specialized aggregations for analyzing operational patterns:
  • stateCount: The total number of data points per state in the time period.
  • stateTransitions: The number of transitions into each state.
  • stateDuration: The total time (milliseconds) spent in each state.
POST /api/v1/projects/{project}/timeseries/data/list
Content-Type: application/json

{
  "items": [{
    "instanceId": {"space": "industrial_assets", "externalId": "valve_001_state"},
    "aggregates": ["count", "countGood", "countUncertain", "stateCount", "stateTransitions", "stateDuration"],
    "granularity": "1h",
    "start": 1609459200000,
    "end": 1609545600000,
    "treatUncertainAsBad": false
  }]
}
Response:
{
  "items": [{
    "instanceId": {"space": "industrial_assets", "externalId": "valve_001_state"},
    "datapoints": [{
      "timestamp": 1609459200000,
      "count": 67,
      "countGood": 59,
      "countUncertain": 8,
      "stateAggregates": [
        {
          "numericValue": 0,
          "stringValue": "CLOSED",
          "stateCount": 45,
          "stateTransitions": 3,
          "stateDuration": 2700000
        },
        {
          "numericValue": 1,
          "stringValue": "OPEN",
          "stateCount": 22,
          "stateTransitions": 3,
          "stateDuration": 900000
        }
      ]
    }]
  }]
}

​
Supported aggregates

State time series support both top-level status aggregates and state-specific aggregates: Top-level aggregates (apply to all data points):
  • count, countGood, countUncertain, countBad
  • durationGood, durationUncertain, durationBad
State-level aggregates (within stateAggregates, only for Good data points):
  • stateCount: The number of data points in this state.
  • stateTransitions: The number of transitions into this state.
  • stateDuration: The total time spent in this state in milliseconds.
For detailed explanations of each aggregate function, including examples and best practices, see State time series aggregates.

​
State set management

State sets can be modified after creation, but changes to state definitions affect how historical data is interpreted in queries and aggregations. Understanding these implications is important when managing state sets over time.

​
Update state sets

State sets are mutable and can be updated after creation. However, changes affect how historical data is interpreted: 
POST /api/v1/projects/{project}/models/instances
Content-Type: application/json

{
  "items": [{
    "space": "state_definitions",
    "externalId": "valve_states",
    "instanceType": "node",
    "sources": [{
      "source": {
        "type": "view",
        "space": "cdf_cdm",
        "externalId": "CogniteStateSet",
        "version": "v1"
      },
      "properties": {
        "states": [
          {"numericValue": 0, "stringValue": "CLOSED"},
          {"numericValue": 1, "stringValue": "OPEN"},
          {"numericValue": 2, "stringValue": "TRANSITIONING"},
          {"numericValue": 3, "stringValue": "FAULT"}
        ]
      }
    }]
  }]
}
Impact of state set changes:
  • Adding states: New states can be added without affecting existing data points.
  • Removing states: Historical data points with removed states retain their numeric values but may not have string values in queries.
  • Changing mappings: If you change the string value for a numeric value, historical data displays with the new string value.

​
Delete state sets

Deleting a state set through data modeling causes all time series referencing it to have an empty state set. The time series and data points remain intact. Without a state set, the only data points that can be ingested are those with a Bad status and a null numeric value.

​
Limitations

The following limitations apply to state time series:
  • Maximum 100 unique states per state set.
  • State time series can only be created through data modeling (not via the time series API).
  • Traditional numeric aggregations (min, max, avg) are not applicable to state time series.
  • No SDK support in the initial private beta.
  • State sets are not immutable (changes affect historical data interpretation).