feat(simulators): Add created_time and simulation_time filters to simulation runs list method (#2274)

Co-authored-by: Luis Pereira <91738660+lpereiracgn@users.noreply.github.com>

Author: evertoncolling

CHANGELOG.md

@@ -21,6 +21,10 @@ As of 2025-08-29, changes are grouped as follows
 ### Added
 - Add `timezone` as an optional param to the WorkflowScheduledTriggerRule.
 
+## [Unreleased]
+### Added
+- [alpha] Support for `created_time` and `simulation_time` filters in `client.simulators.runs.list()` to filter simulation runs by timestamp ranges.
+
 ## [7.82.1] - 2025-08-28
 ### Fixed
 - Fix documentation of files.upload_content. It does not support directories. Use more meaningful errors when the path is not a file. 

cognite/client/_api/simulators/runs.py

@@ -5,6 +5,7 @@
 
 from cognite.client._api_client import APIClient
 from cognite.client._constants import DEFAULT_LIMIT_READ
+from cognite.client.data_classes.shared import TimestampRange
 from cognite.client.data_classes.simulators.filters import SimulatorRunsFilter
 from cognite.client.data_classes.simulators.runs import (
     SimulationRun,
@@ -64,6 +65,8 @@ def __call__(
         routine_external_ids: SequenceNotStr[str] | None = None,
         routine_revision_external_ids: SequenceNotStr[str] | None = None,
         model_revision_external_ids: SequenceNotStr[str] | None = None,
+        created_time: TimestampRange | None = None,
+        simulation_time: TimestampRange | None = None,
     ) -> Iterator[SimulationRunList]: ...
 
     @overload
@@ -79,6 +82,8 @@ def __call__(
         routine_external_ids: SequenceNotStr[str] | None = None,
         routine_revision_external_ids: SequenceNotStr[str] | None = None,
         model_revision_external_ids: SequenceNotStr[str] | None = None,
+        created_time: TimestampRange | None = None,
+        simulation_time: TimestampRange | None = None,
     ) -> Iterator[SimulationRun]: ...
 
     def __call__(
@@ -93,6 +98,8 @@ def __call__(
         routine_external_ids: SequenceNotStr[str] | None = None,
         routine_revision_external_ids: SequenceNotStr[str] | None = None,
         model_revision_external_ids: SequenceNotStr[str] | None = None,
+        created_time: TimestampRange | None = None,
+        simulation_time: TimestampRange | None = None,
     ) -> Iterator[SimulationRun] | Iterator[SimulationRunList]:
         """Iterate over simulation runs
 
@@ -109,6 +116,8 @@ def __call__(
             routine_external_ids (SequenceNotStr[str] | None): Filter by routine external ids
             routine_revision_external_ids (SequenceNotStr[str] | None): Filter by routine revision external ids
             model_revision_external_ids (SequenceNotStr[str] | None): Filter by model revision external ids
+            created_time (TimestampRange | None): Filter by created time
+            simulation_time (TimestampRange | None): Filter by simulation time
 
         Returns:
             Iterator[SimulationRun] | Iterator[SimulationRunList]: yields Simulation Run one by one if chunk is not specified, else SimulatorRunsList objects.
@@ -123,6 +132,8 @@ def __call__(
             routine_external_ids=routine_external_ids,
             routine_revision_external_ids=routine_revision_external_ids,
             model_revision_external_ids=model_revision_external_ids,
+            created_time=created_time,
+            simulation_time=simulation_time,
         )
 
         return self._list_generator(
@@ -145,6 +156,8 @@ def list(
         routine_external_ids: SequenceNotStr[str] | None = None,
         routine_revision_external_ids: SequenceNotStr[str] | None = None,
         model_revision_external_ids: SequenceNotStr[str] | None = None,
+        created_time: TimestampRange | None = None,
+        simulation_time: TimestampRange | None = None,
     ) -> SimulationRunList:
         """`Filter simulation runs <https://developer.cognite.com/api#tag/Simulation-Runs/operation/filter_simulation_runs_simulators_runs_list_post>`_
 
@@ -160,6 +173,8 @@ def list(
             routine_external_ids (SequenceNotStr[str] | None): Filter by routine external ids
             routine_revision_external_ids (SequenceNotStr[str] | None): Filter by routine revision external ids
             model_revision_external_ids (SequenceNotStr[str] | None): Filter by model revision external ids
+            created_time (TimestampRange | None): Filter by created time
+            simulation_time (TimestampRange | None): Filter by simulation time
 
         Returns:
             SimulationRunList: List of simulation runs
@@ -175,6 +190,13 @@ def list(
                 ...     simulator_external_ids=["PROSPER", "DWSIM"],
                 ...     status="success"
                 ... )
+
+            Filter runs by time ranges:
+                >>> from cognite.client.data_classes.shared import TimestampRange
+                >>> res = client.simulators.runs.list(
+                ...     created_time=TimestampRange(min=0, max=1_700_000_000_000),
+                ...     simulation_time=TimestampRange(min=0, max=1_700_000_000_000),
+                ... )
         """
 
         filter_runs = SimulatorRunsFilter(
@@ -186,6 +208,8 @@ def list(
             routine_external_ids=routine_external_ids,
             routine_revision_external_ids=routine_revision_external_ids,
             model_revision_external_ids=model_revision_external_ids,
+            created_time=created_time,
+            simulation_time=simulation_time,
         )
         self._warning.warn()
         return self._list(

cognite/client/data_classes/simulators/filters.py

@@ -63,6 +63,8 @@ def __init__(
         routine_external_ids: str | SequenceNotStr[str] | None = None,
         routine_revision_external_ids: str | SequenceNotStr[str] | None = None,
         model_revision_external_ids: str | SequenceNotStr[str] | None = None,
+        created_time: TimestampRange | None = None,
+        simulation_time: TimestampRange | None = None,
     ) -> None:
         self.model_external_ids = _parse_str_or_sequence(model_external_ids)
         self.simulator_integration_external_ids = _parse_str_or_sequence(simulator_integration_external_ids)
@@ -72,6 +74,8 @@ def __init__(
         self.model_revision_external_ids = _parse_str_or_sequence(model_revision_external_ids)
         self.status = status
         self.run_type = run_type
+        self.created_time = created_time
+        self.simulation_time = simulation_time
 
 
 class SimulatorRoutinesFilter(CogniteFilter):

tests/tests_integration/test_api/test_simulators/test_runs.py

@@ -4,6 +4,7 @@
 import pytest
 
 from cognite.client._cognite_client import CogniteClient
+from cognite.client.data_classes import TimestampRange
 from cognite.client.data_classes.simulators.runs import (
     SimulationInput,
     SimulationOutput,
@@ -123,6 +124,57 @@ def test_create_run(
         assert created_runs[0].routine_external_id == routine_external_id
         assert created_runs[0].id is not None
 
+    def test_list_filtering_timestamp_ranges(
+        self, cognite_client: CogniteClient, seed_resource_names: ResourceNames
+    ) -> None:
+        routine_external_id = seed_resource_names.simulator_routine_external_id
+
+        # Create a run to ensure we have something to filter
+        created_run = cognite_client.simulators.runs.create(
+            [
+                SimulationRunWrite(
+                    run_type="external",
+                    routine_external_id=routine_external_id,
+                )
+            ]
+        )
+        created_run_time = created_run[0].created_time
+
+        # Set a specific simulation time for our test run
+        test_simulation_time = int(time.time() * 1000) - 5000  # 5 seconds ago
+        cognite_client.simulators._post(
+            "/simulators/run/callback",
+            json={
+                "items": [
+                    {
+                        "id": created_run[0].id,
+                        "status": "success",
+                        "simulationTime": test_simulation_time,
+                    }
+                ]
+            },
+        )
+
+        # Test filtering by created_time and simulation_time - use a narrow range around the created run
+        runs_filtered_both = cognite_client.simulators.runs.list(
+            routine_external_ids=[routine_external_id],
+            created_time=TimestampRange(min=created_run_time - 1000, max=created_run_time + 1000),
+            simulation_time=TimestampRange(min=test_simulation_time - 1000, max=test_simulation_time + 1000),
+            limit=100,
+        )
+        assert len(runs_filtered_both) > 0
+        assert created_run[0].id in [run.id for run in runs_filtered_both]
+
+        # Test with empty time range for created_time and simulation_time (should return no results)
+        current_time_ms = int(time.time() * 1000)
+        runs_empty_range = cognite_client.simulators.runs.list(
+            routine_external_ids=[routine_external_id],
+            created_time=TimestampRange(min=current_time_ms + 20000, max=current_time_ms + 30000),
+            simulation_time=TimestampRange(min=current_time_ms + 20000, max=current_time_ms + 30000),
+            limit=5,
+        )
+        assert len(runs_empty_range) == 0
+
     def test_list_run_data(self, cognite_client: CogniteClient, seed_resource_names: ResourceNames) -> None:
         routine_external_id = seed_resource_names.simulator_routine_external_id
         created_run = cognite_client.simulators.runs.create(