---
title: dots.v2.genAi.simulation_runs.get()
description: List Simulation Runs
product: Reference
url: https://docs.digitalocean.com/reference/dots/reference/agent-platform-api/genai-list-simulation-runs/
last_updated: "2026-11-18"
---

> **For AI agents:** The documentation index is at [https://docs.digitalocean.com/llms.txt](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).

# dots.v2.genAi.simulation_runs.get()

Generated on 18 Nov 2026 from DoTs version [`v1.25.0`](https://github.com/digitalocean/dots/releases/tag/v1.25.0)

## Usage

```typescript
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`](https://docs.digitalocean.com/reference/api/reference/agent-platform-api/index.html.md#genai_list_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

```typescript
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:

```typescript
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

```json
{
  "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": "example@example.com",
      "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`](https://docs.digitalocean.com/reference/api/reference/agent-platform-api/index.html.md#genai_list_simulation_runs) in the API reference for additional detail on responses, headers, parameters, and more.