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_timeseries

Getting started

pip install --upgrade cognite-sdk  
# or  
uv add cognite-sdk

from 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