Give Feedback

pydo.genai.list_simulation_runs()

Generated on 1 Oct 2026 from pydo version v0.43.0

Copy page as Markdown View page as Markdown

Usage

client.genai.list_simulation_runs(
    scenario_set_uuid=None,
    page=None,
    per_page=None,
    statuses=None,
    search=None,
    sort_by="SIMULATION_RUN_SORT_FIELD_UNSPECIFIED",
    sort_direction="SORT_DIRECTION_UNSPECIFIED",
)

Returns JSONRaises HttpResponseError

Description

To list simulation runs, send a GET request to /v2/gen-ai/simulation_runs.

Parameters

scenario_set_uuid string optional

Optional filter by scenario set.

page integer optional

Page number.

per_page integer optional

Items per page.

statuses array of strings optional

Filter by one or more statuses. Empty means no status filter.

- SIMULATION_RUN_STATUS_PENDING: Accepted and queued, not yet executing.
- SIMULATION_RUN_STATUS_RUNNING: Journeys are executing.
- SIMULATION_RUN_STATUS_SUCCEEDED: All journeys finished successfully.
- SIMULATION_RUN_STATUS_FAILED: The run failed, for example because of a timeout or workflow error.
- SIMULATION_RUN_STATUS_CANCELLED: The run was cancelled.
- SIMULATION_RUN_STATUS_EVALUATING: Journeys finished and an attached evaluation is running. Only reachable
when the create request included evaluation_config. When the evaluation
reaches a terminal status, its outcome is reflected in the simulation run
status.
- SIMULATION_RUN_STATUS_PARTIALLY_SUCCESSFUL: The simulation or its attached evaluation completed with a mixture of
successful and failed results.

search string optional

Free-text search across the run name and scenario set name
(case-insensitive substring match). Empty means no search.

sort_by string optional

Field to sort by. Defaults to creation date when unspecified.

- SIMULATION_RUN_SORT_FIELD_CREATED_AT: Sort by creation date. Default.
- SIMULATION_RUN_SORT_FIELD_NAME: Sort by customer-supplied run name (case-insensitive).
- SIMULATION_RUN_SORT_FIELD_STATUS: Sort by status using lifecycle order (pending → running → terminal).
- SIMULATION_RUN_SORT_FIELD_UPDATED_AT: Sort by last update date.

One of: SIMULATION_RUN_SORT_FIELD_UNSPECIFIED, SIMULATION_RUN_SORT_FIELD_CREATED_AT, SIMULATION_RUN_SORT_FIELD_NAME, SIMULATION_RUN_SORT_FIELD_STATUS, SIMULATION_RUN_SORT_FIELD_UPDATED_AT

Default: SIMULATION_RUN_SORT_FIELD_UNSPECIFIED

sort_direction string optional

Sort direction. Defaults to descending when unspecified.

One of: SORT_DIRECTION_UNSPECIFIED, SORT_DIRECTION_ASC, SORT_DIRECTION_DESC

Default: SORT_DIRECTION_UNSPECIFIED

Pagination

This method returns paginated results. The response includes a links.pages object with URLs for navigating between pages. To retrieve the next page, parse the next URL and pass the page parameter:

from urllib.parse import urlparse, parse_qs

resp = client.genai.list_simulation_runs()
pages = resp.get("links", {}).get("pages", {})

while "next" in pages:
    parsed = urlparse(pages["next"])
    page = int(parse_qs(parsed.query)["page"][0])
    resp = client.genai.list_simulation_runs(page=page)
    pages = resp.get("links", {}).get("pages", {})

Response Example

Show Response Example

{
  "available_sort_by": [
    "SIMULATION_RUN_SORT_FIELD_UNSPECIFIED"
  ],
  "available_sort_directions": [
    "SORT_DIRECTION_UNSPECIFIED"
  ],
  "available_statuses": [
    "SIMULATION_RUN_STATUS_UNSPECIFIED"
  ],
  "links": {
    "pages": {
      "first": "example string",
      "last": "example string",
      "next": "example string",
      "previous": "example string"
    }
  },
  "meta": {
    "page": 123,
    "pages": 123,
    "total": 123
  },
  "simulation_runs": [
    {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by_user_email": "[email protected]",
      "created_by_user_id": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "evaluation_run_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "exploration_budget": 123,
      "failure_reason": "example string",
      "journeys_finished": 123,
      "judge_model_name": "example name",
      "judge_model_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "max_turns": 123,
      "name": "example name",
      "run_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "scenario_count": 123,
      "scenario_set_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "status": "SIMULATION_RUN_STATUS_UNSPECIFIED",
      "total_journeys": 123,
      "updated_at": "2023-01-01T00:00:00Z",
      "user_simulator_model_name": "example name",
      "user_simulator_model_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "workflow_uuid": "123e4567-e89b-12d3-a456-426614174000"
    }
  ]
}

More Information

See /v2/gen-ai/simulation_runs in the API reference for additional detail on responses, headers, parameters, and more.