dots.v2.genAi.simulation_runs.get()

Generated on 13 Nov 2026 from DoTs version v1.24.0

Usage

client.v2.genAi.simulation_runs.get(requestConfiguration?: RequestConfiguration<Simulation_runsRequestBuilderGetQueryParameters>): Promise<undefined | ApiListSimulationRunsOutput>

Description

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

Parameters

scenarioSetUuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

Optional filter by scenario set.

page integer optional

Example: 1

Page number.

perPage integer optional

Example: 1

Items per page.

statuses array of strings optional

Example: ["SIMULATION_RUN_STATUS_RUNNING"]

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: Episodes are executing.
- SIMULATION_RUN_STATUS_SUCCEEDED: All episodes 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: Episodes 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

Example: example string

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

sortBy 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

sortDirection string optional

Sort direction. Defaults to descending when unspecified.

One of: SORT_DIRECTION_UNSPECIFIED, SORT_DIRECTION_ASC, SORT_DIRECTION_DESC

Default: SORT_DIRECTION_UNSPECIFIED

Request Sample

Show Request Sample
import { FetchRequestAdapter } from "@microsoft/kiota-http-fetchlibrary";
import {
    createDigitalOceanClient,
    DigitalOceanApiKeyAuthenticationProvider,
} from "@digitalocean/dots";

const authProvider = new DigitalOceanApiKeyAuthenticationProvider(process.env.DIGITALOCEAN_TOKEN!);
const adapter = new FetchRequestAdapter(authProvider);
const client = createDigitalOceanClient(adapter);

const response = await client.v2.genAi.simulation_runs.get();

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 query parameter:

let response = await client.v2.genAi.simulation_runs.get();
let pages = response?.links?.pages;

while (pages && "next" in pages && typeof pages.next === "string") {
    const page = Number(new URL(pages.next).searchParams.get("page"));
    response = await client.v2.genAi.simulation_runs.get({
        queryParameters: {
            page,
        },
    });
    pages = response?.links?.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",
      "episodes_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_episodes": 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.

We can't find any results for your search.

Try using different keywords or simplifying your search terms.