--- title: "List Simulations" method: GET path: "/simulations" tags: ["Simulations"] --- # List Simulations `GET /simulations` ## Request - Base URL: `https://api.ionworks.com` - URL: `https://api.ionworks.com/simulations` - Auth: none declared List simulations filtered by a parameterized model, study, or protocol. Scope by exactly one of ``parameterized_model_id`` or ``study_id``, or by ``experiment_template_id`` alone. ``experiment_template_id`` may also be combined with either of the other two to narrow it to one protocol, which is how a client finds the existing runs of one model on one protocol. 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. Combines with ``parameterized_model_id`` or ``study_id``. 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. state : {"queued", "running", "completed", "failed"}, optional The same filter by coarse state: ``queued`` is pending or waiting, ``failed`` includes canceled. Give at most one of ``status`` and ``state``. 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. summary : bool, optional Leave out each run's ``metrics`` and ``storage_folder``, and the model scalar parameter map, so a listing stays small. Defaults to False. Returns ------- ListSimulationsResponse Simulations, model scalar parameters map, and total count. ## Query parameters - `parameterized_model_id` string, uuid, nullable - `study_id` string, uuid, nullable - `experiment_template_id` string, uuid, nullable - `limit` integer - `offset` integer - `status` string, nullable - `state` 'queued' | 'running' | 'completed' | 'failed', 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 - `summary` boolean ## 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. - `project_id` string, nullable: The project the simulation belongs to: its experiment's project. - `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. - `simulation_options` object, nullable: Options the simulation was run with; part of its identity, so a rerun must send them back. - `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. - `protocol_id` string, nullable: The saved protocol (experiment template) the simulation ran; the same id the run and list endpoints take as a protocol. - `protocol_name` string, nullable: That protocol's name. - `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 ## Changes - **2026-10-24** `f4c74e855466`: 4 info - added the new optional `query` request parameter `state` - added the new optional `query` request parameter `summary` - added the optional property `simulations/items/protocol_id` to the response with the `200` status - added the optional property `simulations/items/protocol_name` to the response with the `200` status - **2026-10-22** `aecee6d998fb`: 1 info - added the optional property `simulations/items/project_id` to the response with the `200` status - **2026-09-30** `ea3d377fec1a`: 3 breaking, 1 info - for the `query` request parameter `experiment_template_id`, the format of property `anyOf[subschema #1]/` was specialized from no format to `uuid` - for the `query` request parameter `parameterized_model_id`, the format of property `anyOf[subschema #1]/` was specialized from no format to `uuid` - for the `query` request parameter `study_id`, the format of property `anyOf[subschema #1]/` was specialized from no format to `uuid` - added the optional property `simulations/items/simulation_options` to the response with the `200` status [Operation history](https://skmtc.dev/ionworks/apis/ionworks-api/changes/simulations/get.md) --- [API](https://skmtc.dev/ionworks/apis/ionworks-api.md) - [All operations](https://skmtc.dev/ionworks/apis/ionworks-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ionworks/apis/ionworks-api/revisions/abebbbc5f60a?raw)