For AI agents: The documentation index is at https://docs.digitalocean.com/llms.txt. Markdown versions of pages use the same URL with index.html.md in place of the HTML page (for example, append index.html.md to the directory path instead of opening the HTML document).

Usage

client.genai.list_simulation_journeys(
    run_uuid="\"123e4567-e89b-12d3-a456-426614174000\"",
    scenario_uuid=None,
    page=None,
    per_page=None,
    statuses=None,
    verdicts=None,
    search=None,
    sort_by="SIMULATION_JOURNEY_SORT_FIELD_UNSPECIFIED",
    sort_direction="SORT_DIRECTION_UNSPECIFIED",
)

Description

To list the journeys within a simulation run, send a GET request to /v2/gen-ai/simulation_runs/{run_uuid}/journeys.

Parameters

run_uuid string required

UUID of the run whose journeys to list.

scenario_uuid string optional

Optional filter by scenario.

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_JOURNEY_STATUS_RUNNING: The journey is executing and a trajectory is available to retrieve.
- SIMULATION_JOURNEY_STATUS_FINISHED: The journey reached a stop condition and produced a verdict.
- SIMULATION_JOURNEY_STATUS_FAILED: The journey failed because of a cancel, timeout, or error.
- SIMULATION_JOURNEY_STATUS_PREPARING: The journey is allocated but its trajectory is not available yet.

verdicts array of strings optional

Filter by one or more verdicts. Empty means no verdict filter.

- SIMULATION_JOURNEY_VERDICT_SUCCESS: The candidate agent satisfied the scenario's stopping criteria.
- SIMULATION_JOURNEY_VERDICT_FAILURE: The candidate agent did not satisfy the stopping criteria.
- SIMULATION_JOURNEY_VERDICT_INCONCLUSIVE: No conclusive verdict (e.g. max_turns reached without the judge finishing).

search string optional

Free-text search across scenario_uuid and session_id
(case-insensitive substring match). Empty means no search.

sort_by string optional

Field to sort by. Defaults to scenario ordering when unspecified.

- SIMULATION_JOURNEY_SORT_FIELD_SCENARIO: Sort by scenario_uuid then journey_index. Default.
- SIMULATION_JOURNEY_SORT_FIELD_CREATED_AT: Sort by creation date.
- SIMULATION_JOURNEY_SORT_FIELD_STATUS: Sort by journey status using lifecycle order.
- SIMULATION_JOURNEY_SORT_FIELD_VERDICT: Sort by verdict (nulls last).

One of: SIMULATION_JOURNEY_SORT_FIELD_UNSPECIFIED, SIMULATION_JOURNEY_SORT_FIELD_SCENARIO, SIMULATION_JOURNEY_SORT_FIELD_CREATED_AT, SIMULATION_JOURNEY_SORT_FIELD_STATUS, SIMULATION_JOURNEY_SORT_FIELD_VERDICT

Default: SIMULATION_JOURNEY_SORT_FIELD_UNSPECIFIED

sort_direction string optional

Sort direction. Defaults to ascending 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_journeys(run_uuid="\"123e4567-e89b-12d3-a456-426614174000\"", )
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_journeys(run_uuid="\"123e4567-e89b-12d3-a456-426614174000\"", page=page)
    pages = resp.get("links", {}).get("pages", {})

Response Example

{
  "available_sort_by": [
    "SIMULATION_JOURNEY_SORT_FIELD_UNSPECIFIED"
  ],
  "available_sort_directions": [
    "SORT_DIRECTION_UNSPECIFIED"
  ],
  "available_statuses": [
    "SIMULATION_JOURNEY_STATUS_UNSPECIFIED"
  ],
  "available_verdicts": [
    "SIMULATION_JOURNEY_VERDICT_UNSPECIFIED"
  ],
  "journeys": [
    {
      "created_at": "2023-01-01T00:00:00Z",
      "duration_sec": "12345",
      "failure_reason": "example string",
      "journey_index": 123,
      "journey_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "judge_reasoning": "example string",
      "run_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "scenario_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "session_id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "SIMULATION_JOURNEY_STATUS_UNSPECIFIED",
      "trajectory_bucket_name": "example name",
      "trajectory_bucket_region": "example string",
      "trajectory_spaces_key": "example string",
      "updated_at": "2023-01-01T00:00:00Z",
      "verdict": "SIMULATION_JOURNEY_VERDICT_UNSPECIFIED"
    }
  ],
  "links": {
    "pages": {
      "first": "example string",
      "last": "example string",
      "next": "example string",
      "previous": "example string"
    }
  },
  "meta": {
    "page": 123,
    "pages": 123,
    "total": 123
  }
}

More Information

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