> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Simulations

> List simulations filtered by either a parameterized model or a study.

Exactly one of ``parameterized_model_id`` or ``study_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.
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.

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



## OpenAPI

````yaml https://api.ionworks.com/openapi.json get /simulations
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://api.ionworks.com
    description: Production
security: []
paths:
  /simulations:
    get:
      tags:
        - Simulations
      summary: List Simulations
      description: >-
        List simulations filtered by either a parameterized model or a study.


        Exactly one of ``parameterized_model_id`` or ``study_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.
        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.

        Returns

        -------

        ListSimulationsResponse
            Simulations, model scalar parameters map, and total count.
      operationId: list_simulations_simulations_get
      parameters:
        - name: parameterized_model_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Parameterized Model Id
        - name: study_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Study Id
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 1000
            minimum: 1
            title: Limit
            default: 100
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            title: Offset
            default: 0
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSimulationsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ListSimulationsResponse:
      properties:
        simulations:
          items:
            $ref: '#/components/schemas/SimulationSummary'
          type: array
          title: Simulations
          description: List of simulation summaries without full parameters
        model_scalar_parameters:
          additionalProperties:
            additionalProperties: true
            type: object
          type: object
          title: Model Scalar Parameters
          description: >-
            Map of parameterized_model_id to scalar-only parameters. Used as
            fallback when design.design_parameters doesn't have a value.
        total:
          type: integer
          title: Total
          description: Total number of matching simulations.
          default: 0
      type: object
      required:
        - simulations
      title: ListSimulationsResponse
      description: |-
        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.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SimulationSummary:
      properties:
        id:
          type: string
          title: Id
          description: The unique identifier for the simulation.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Timestamp of when the simulation was created.
        updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updated At
          description: Timestamp of when the simulation was last updated.
        experiment_id:
          type: string
          title: Experiment Id
          description: The ID of the experiment this simulation belongs to.
        parameterized_model_id:
          type: string
          title: Parameterized Model Id
          description: The ID of the parameterized model used for this simulation.
        design_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Design Id
          description: The ID of the design for this simulation.
        job_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Job Id
          description: The ID of the job running this simulation.
        status:
          anyOf:
            - type: string
            - type: 'null'
          title: Status
          description: The current status of the job running this simulation.
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
          description: Error message if the job failed.
        error_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Code
          description: Machine-readable error code.
        metrics:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metrics
          description: Computed metrics from the simulation.
        storage_folder:
          anyOf:
            - type: string
            - type: 'null'
          title: Storage Folder
          description: >-
            Folder path in storage containing simulation files
            (solution.parquet, time_series.parquet, steps.parquet).
        organization_id:
          type: string
          title: Organization Id
          description: Organization this simulation belongs to.
        experiment:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Experiment
          description: The experiment this simulation belongs to (id and template).
        parameterized_model:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Parameterized Model
          description: The parameterized model (id and name only).
        design:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Design
          description: The design used for this simulation.
      type: object
      required:
        - id
        - created_at
        - experiment_id
        - parameterized_model_id
        - organization_id
      title: SimulationSummary
      description: |-
        Simulation summary model for study listings.

        Used for listing simulations where full parameters and simulation_data
        are not needed. Optimized for table views with minimal payload.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

````