State time series support in the Cognite Python SDK
Hi everyone,The Cognite Python SDK now supports State time series, from cognite-sdk 8.20.0.State time series track the discrete states of equipment, such as OPEN/CLOSED or RUNNING/STANDBY/ERROR. Each time series links to a state set that defines the valid states. CDF validates datapoints against that set and offers aggregates built for states: time spent in each state, number of transitions into each state, and count per state. If State time series are new to you, start here: https://docs.cognite.com/dev/concepts/resource_types/state_timeseriesGetting startedpip install --upgrade cognite-sdk # or uv add cognite-sdkfrom datetime import datetime, timezone from cognite.client import CogniteClient from cognite.client.data_classes import ( StateDatapointsInsert, StateDatapointWrite,)from cognite.client.data_classes.data_modeling import NodeId, StateSetEntry from cognite.client.data_classes.data_modeling.cdm.v1 import ( CogniteStateSetApply, CogniteTimeSeriesApply, ) client = CogniteClient() # 1. Define the valid states and create a state time series that uses them state_set = CogniteStateSetApply( "my-space", "pump-states", name="Pump states", states=[ StateSetEntry(0, "OFF"), StateSetEntry(1, "RUNNING"), StateSetEntry(2, "STANDBY"), ], ) pump_state = CogniteTimeSeriesApply( "my-space", "pump-101-state", is_step=True, time_series_type="state", state_set=("my-space", "pump-states"), name="Pump 101 state", ) client.data_modeling.instances.apply([state_set, pump_state]) # 2. Insert datapoints by numeric or string value ts_id = NodeId("my-space", "pump-101-state") client.time_series.data.insert_states( StateDatapointsInsert( instance_id=ts_id, datapoints=[ StateDatapointWrite( datetime(2026, 10, 1, 0, tzinfo=timezone.utc), 1 ), StateDatapointWrite( datetime(2026, 10, 1, 6, tzinfo=timezone.utc), string_value="STANDBY" ), StateDatapointWrite( datetime(2026, 10, 1, 9, tzinfo=timezone.utc), string_value="RUNNING" ), ], ) ) # 3. Time spent in each state per day, one column per state df = client.time_series.data.retrieve_dataframe( instance_id=ts_id, start=datetime(2026, 10, 1, tzinfo=timezone.utc), end=datetime(2026, 10, 3, tzinfo=timezone.utc), aggregates="state_duration", granularity="1d", )Reference docs:insert_states: https://cognite-sdk-python.readthedocs-hosted.com/en/stable/generated/cognite.client.AsyncCogniteClient.time_series.data.insert_states.html Datapoints API: https://cognite-sdk-python.readthedocs-hosted.com/en/stable/time_series.html Core data model: https://cognite-sdk-python.readthedocs-hosted.com/en/stable/data_modeling/core_data_model.html
Check the
documentation
Ask the
Community
Take a look
at
Academy
Cognite
Status
Page
Contact
Cognite Support

