Skip to main content
State time series track the discrete operational states of industrial equipment over time. Each data point holds one state from a predefined set of valid states, so you can query and analyze equipment states without mapping codes to labels yourself. To compare state time series with numeric and string time series, see About time series types. 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

State time series build on two concepts: state sets, which define the valid states, and state transitions, which track how equipment moves between states over time.

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
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

You create state time series and state sets as instances with the data modeling API, and ingest and retrieve state data points with the time series data points API. The following examples show how to work with state time series and state sets.

Create state time series

To create a state time series, set the type property to state and link to a state set:

Create state sets

State sets are created through data modeling using the CogniteStateSet view:

Ingest state data

State data points can include both numeric and string values. If both are provided, they must correspond to the same state:
To ingest state time series from OPC UA in data modeling projects, see Extracting state time series with the OPC UA extractor.

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:
Response:

Retrieve state aggregates

State time series support the common aggregates and the state aggregates. This example requests both:
Response:

State set management

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

Update state sets

To update a state set, update the states property through the CogniteStateSet view:
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.
Last modified on November 16, 2026