---
title: "List Simulations"
method: GET
path: "/simulations"
tags: ["Simulations"]
---

# List Simulations

`GET /simulations`

List simulations filtered by a parameterized model, study, or protocol.

Exactly one of ``parameterized_model_id``, ``study_id``, or
``experiment_template_id`` must be provided. Returns simulation summaries
without simulation_data, plus a map of model scalar parameters
deduplicated by parameterized_model_id.

Parameters
----------
parameterized_model_id : str, optional
    Filter simulations belonging to this parameterized model.
study_id : str, optional
    Filter simulations assigned to this study.
experiment_template_id : str, optional
    Filter simulations whose experiment references this protocol template.
limit : int, optional
    Maximum number of results to return. Must be between 1 and 1000. Defaults to 100.
offset : int, optional
    Number of results to skip for pagination. Must be >= 0. Defaults to 0.
status : str, optional
    PostgREST filter expression on the simulation's job status, e.g.
    ``"eq.completed"`` or ``"in.(pending,processing,waiting)"``. When
    provided, only simulations whose job matches are returned.
model_name, protocol_name : str, optional
    Exact-match expressions (e.g. ``"eq.My model"``) on the joined
    parameterized model name and protocol (experiment template) name. A
    simulation has no name of its own, so these two are what identify it.
created_at_gt, created_at_lt, updated_at_gt, updated_at_lt : str, optional
    ISO datetime strings for date-range (between) filtering on the native
    ``created_at`` / ``updated_at`` columns.

Returns
-------
ListSimulationsResponse
    Simulations, model scalar parameters map, and total count.

## Query parameters

- `parameterized_model_id` string, nullable
- `study_id` string, nullable
- `experiment_template_id` string, nullable
- `limit` integer
- `offset` integer
- `status` string, nullable
- `model_name` string, nullable
- `protocol_name` string, nullable
- `created_at_gt` string, nullable
- `created_at_lt` string, nullable
- `updated_at_gt` string, nullable
- `updated_at_lt` string, nullable

## Response `200`

Successful Response

- ListSimulationsResponse — Response for study simulations with deduplicated model parameters. Instead of including full parameters on each simulation (which can be massive expression trees), this response includes simulations without parameters and a separate map of model_id -> scalar parameters. The frontend can merge: design.design_parameters over model base params.
  - `simulations` SimulationSummary[], required — List of simulation summaries without full parameters
    - `id` string, required — The unique identifier for the simulation.
    - `created_at` string, date-time, required — Timestamp of when the simulation was created.
    - `updated_at` string, date-time, nullable — Timestamp of when the simulation was last updated.
    - `experiment_id` string, required — The ID of the experiment this simulation belongs to.
    - `parameterized_model_id` string, required — The ID of the parameterized model used for this simulation.
    - `design_id` string, nullable — The ID of the design for this simulation.
    - `job_id` string, nullable — The ID of the job running this simulation.
    - `status` string, nullable — The current status of the job running this simulation.
    - `error` string, nullable — Error message if the job failed.
    - `error_code` string, nullable — Machine-readable error code.
    - `metrics` object, nullable — Computed metrics from the simulation.
    - `storage_folder` string, nullable — Folder path in storage containing simulation files (solution.parquet, time_series.parquet, steps.parquet).
    - `organization_id` string, required — Organization this simulation belongs to.
    - `experiment` object, nullable — The experiment this simulation belongs to (id and template).
    - `parameterized_model` object, nullable — The parameterized model (id and name only).
    - `design` object, nullable — The design used for this simulation.
  - `model_scalar_parameters` object — Map of parameterized_model_id to scalar-only parameters. Used as fallback when design.design_parameters doesn't have a value.
  - `total` integer — Total number of matching simulations.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/ionworks/apis/fastapi.md) · [All operations](https://skmtc.dev/ionworks/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ionworks/fastapi/revisions/7337a3cbdaf2/schema)