> ## 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.

# Dry Run

> Execute an unsaved recipe once, never touching the cache.



## OpenAPI

````yaml https://api.ionworks.com/openapi.json post /projects/{project_id}/dashboards/dry-run
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://api.ionworks.com
    description: Production
security: []
paths:
  /projects/{project_id}/dashboards/dry-run:
    post:
      tags:
        - dashboards
      summary: Dry Run
      description: Execute an unsaved recipe once, never touching the cache.
      operationId: dry_run_projects__project_id__dashboards_dry_run_post
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Project Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DryRunRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FigureResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    DryRunRequest:
      properties:
        config:
          $ref: '#/components/schemas/PlotConfig'
        params:
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
          type: object
          title: Params
      additionalProperties: false
      type: object
      required:
        - config
      title: DryRunRequest
    FigureResult:
      properties:
        plot_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Plot Id
        ok:
          type: boolean
          title: Ok
        figure:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Figure
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
        warnings:
          items:
            type: string
          type: array
          title: Warnings
        provenance_summary:
          additionalProperties:
            type: integer
          type: object
          title: Provenance Summary
        cached:
          type: boolean
          title: Cached
          default: false
        cost:
          $ref: '#/components/schemas/Cost'
        summary:
          anyOf:
            - $ref: '#/components/schemas/FigureSummary'
            - type: 'null'
        datasets_summary:
          anyOf:
            - additionalProperties:
                $ref: '#/components/schemas/DatasetSummary'
              type: object
            - type: 'null'
          title: Datasets Summary
        controls:
          anyOf:
            - additionalProperties:
                items:
                  $ref: '#/components/schemas/ControlOption'
                type: array
              type: object
            - type: 'null'
          title: Controls
      type: object
      required:
        - ok
      title: FigureResult
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PlotConfig:
      properties:
        plan:
          $ref: '#/components/schemas/Plan'
        transform:
          type: string
          maxLength: 100000
          minLength: 1
          title: Transform
        params:
          additionalProperties:
            $ref: '#/components/schemas/Param'
          type: object
          maxProperties: 30
          title: Params
      additionalProperties: false
      type: object
      required:
        - plan
        - transform
      title: PlotConfig
      description: What a saved plot stores.
    JsonValue: {}
    Cost:
      properties:
        sources:
          type: integer
          title: Sources
          default: 0
        rows:
          type: integer
          title: Rows
          default: 0
        points:
          type: integer
          title: Points
          default: 0
        ms:
          type: integer
          title: Ms
          default: 0
      type: object
      title: Cost
    FigureSummary:
      properties:
        traces:
          type: integer
          title: Traces
        points:
          type: integer
          title: Points
        trace_names:
          items:
            type: string
          type: array
          title: Trace Names
        x_range:
          anyOf:
            - items:
                anyOf:
                  - type: number
                  - type: 'null'
              type: array
            - type: 'null'
          title: X Range
        y_range:
          anyOf:
            - items:
                anyOf:
                  - type: number
                  - type: 'null'
              type: array
            - type: 'null'
          title: Y Range
      type: object
      required:
        - traces
        - points
        - trace_names
      title: FigureSummary
      description: What the agent sees about a rendered figure without the whole payload.
    DatasetSummary:
      properties:
        kind:
          type: string
          enum:
            - rows
            - series
            - other
          title: Kind
        rows:
          anyOf:
            - type: integer
            - type: 'null'
          title: Rows
        ids:
          anyOf:
            - type: integer
            - type: 'null'
          title: Ids
        points:
          anyOf:
            - type: integer
            - type: 'null'
          title: Points
        columns:
          additionalProperties:
            $ref: '#/components/schemas/ColumnStats'
          type: object
          title: Columns
      type: object
      required:
        - kind
      title: DatasetSummary
      description: >-
        One executed step, as the author needs to see it before trusting a
        figure.
    ControlOption:
      properties:
        value:
          anyOf:
            - type: string
            - type: integer
            - type: number
            - type: boolean
          title: Value
        label:
          anyOf:
            - type: string
              maxLength: 200
            - type: 'null'
          title: Label
      additionalProperties: false
      type: object
      required:
        - value
      title: ControlOption
      description: 'One select choice: ``value`` reaches the recipe, ``label`` is displayed.'
    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
    Plan:
      properties:
        steps:
          additionalProperties:
            oneOf:
              - $ref: '#/components/schemas/ListStep'
              - $ref: '#/components/schemas/SeriesStep'
              - $ref: '#/components/schemas/SummaryStep'
              - $ref: '#/components/schemas/AggregateStep'
              - $ref: '#/components/schemas/JoinStep'
            discriminator:
              propertyName: op
              mapping:
                aggregate:
                  $ref: '#/components/schemas/AggregateStep'
                join:
                  $ref: '#/components/schemas/JoinStep'
                list:
                  $ref: '#/components/schemas/ListStep'
                series:
                  $ref: '#/components/schemas/SeriesStep'
                summary:
                  $ref: '#/components/schemas/SummaryStep'
          type: object
          maxProperties: 20
          minProperties: 1
          title: Steps
        caps:
          $ref: '#/components/schemas/Caps'
      additionalProperties: false
      type: object
      required:
        - steps
      title: Plan
      description: 'The declarative data plan: named steps executed in order.'
    Param:
      properties:
        kind:
          type: string
          enum:
            - data
            - view
          title: Kind
        default:
          $ref: '#/components/schemas/JsonValue'
        control:
          $ref: '#/components/schemas/Control'
      additionalProperties: false
      type: object
      required:
        - kind
        - default
      title: Param
      description: >-
        A recipe input.


        ``data`` params bind into the plan and key the dataset cache; ``view``
        params

        reach only the transform and key the figure cache, so changing one never

        re-reads a source.
    ColumnStats:
      properties:
        count:
          type: integer
          title: Count
        min:
          anyOf:
            - type: number
            - type: 'null'
          title: Min
        max:
          anyOf:
            - type: number
            - type: 'null'
          title: Max
        nan:
          anyOf:
            - type: integer
            - type: 'null'
          title: Nan
      type: object
      required:
        - count
      title: ColumnStats
      description: >-
        What one column of an executed step held. ``min``/``max``/``nan`` are
        set for

        numeric columns only; a string column reports ``count`` alone.
    ListStep:
      properties:
        op:
          type: string
          const: list
          title: Op
        source:
          type: string
          enum:
            - instances
            - measurements
            - analyses
            - materials
            - materialProperties
            - simulations
            - cellSpecifications
          title: Source
        where:
          $ref: '#/components/schemas/Filters'
        fields:
          items:
            type: string
          type: array
          maxItems: 30
          title: Fields
        limit:
          type: integer
          maximum: 1000
          minimum: 1
          title: Limit
          default: 100
      additionalProperties: false
      type: object
      required:
        - op
        - source
      title: ListStep
      description: Read metadata rows from one source.
    SeriesStep:
      properties:
        op:
          type: string
          const: series
          title: Op
        source:
          type: string
          enum:
            - measurements
            - analyses
            - materialProperties
            - simulations
          title: Source
        ids:
          anyOf:
            - items:
                anyOf:
                  - type: string
                  - type: integer
                  - type: number
                  - type: boolean
                  - type: 'null'
              type: array
            - type: string
            - $ref: '#/components/schemas/StepRef'
          title: Ids
        x:
          type: string
          maxLength: 200
          title: X
        columns:
          items:
            type: string
          type: array
          maxItems: 12
          minItems: 1
          title: Columns
        window:
          $ref: '#/components/schemas/Window'
        max_points:
          type: integer
          maximum: 10000
          minimum: 1
          title: Max Points
          default: 2000
      additionalProperties: false
      type: object
      required:
        - op
        - source
        - ids
        - x
        - columns
      title: SeriesStep
      description: >-
        Read sampled series (time series, curves) for one or more sources.


        The result is keyed by source id: ``{id: {columns: {name: [...]},
        complete}}``.
    SummaryStep:
      properties:
        op:
          type: string
          const: summary
          title: Op
        source:
          type: string
          const: measurements
          title: Source
          default: measurements
        dataset:
          type: string
          enum:
            - steps
            - cycles
          title: Dataset
        ids:
          anyOf:
            - items:
                anyOf:
                  - type: string
                  - type: integer
                  - type: number
                  - type: boolean
                  - type: 'null'
              type: array
            - type: string
            - $ref: '#/components/schemas/StepRef'
          title: Ids
        columns:
          items:
            type: string
          type: array
          maxItems: 12
          minItems: 1
          title: Columns
      additionalProperties: false
      type: object
      required:
        - op
        - dataset
        - ids
        - columns
      title: SummaryStep
      description: >-
        Read exact per-step or per-cycle summary rows for measurements.


        The result is row-shaped: one record per step/cycle with a
        ``measurement_id``

        column added, so it can feed ``aggregate`` and ``join``.
    AggregateStep:
      properties:
        op:
          type: string
          const: aggregate
          title: Op
        input:
          type: string
          pattern: ^[A-Za-z_][A-Za-z0-9_]*$
          title: Input
        group_by:
          items:
            type: string
          type: array
          maxItems: 4
          minItems: 1
          title: Group By
        sort_by:
          anyOf:
            - type: string
              maxLength: 200
            - type: 'null'
          title: Sort By
        metrics:
          additionalProperties:
            $ref: '#/components/schemas/Metric'
          type: object
          maxProperties: 20
          minProperties: 1
          title: Metrics
      additionalProperties: false
      type: object
      required:
        - op
        - input
        - group_by
        - metrics
      title: AggregateStep
      description: Reduce a row-shaped step to one row per group, computed on the server.
    JoinStep:
      properties:
        op:
          type: string
          const: join
          title: Op
        left:
          type: string
          pattern: ^[A-Za-z_][A-Za-z0-9_]*$
          title: Left
        right:
          type: string
          pattern: ^[A-Za-z_][A-Za-z0-9_]*$
          title: Right
        'on':
          additionalProperties:
            type: string
          propertyNames:
            enum:
              - left
              - right
          type: object
          title: 'On'
        fields:
          items:
            type: string
          type: array
          maxItems: 30
          title: Fields
        where:
          anyOf:
            - additionalProperties:
                $ref: '#/components/schemas/JsonValue'
              type: object
            - type: 'null'
          title: Where
          description: 'Post-join equality filter: column → value or list of values.'
        how:
          type: string
          enum:
            - inner
            - left
          title: How
          default: inner
      additionalProperties: false
      type: object
      required:
        - op
        - left
        - right
        - 'on'
      title: JoinStep
      description: Attach columns of one row-shaped step to another by key equality.
    Caps:
      properties:
        max_sources:
          type: integer
          maximum: 500
          minimum: 1
          title: Max Sources
          default: 500
        max_summary_rows:
          type: integer
          maximum: 200000
          minimum: 1
          title: Max Summary Rows
          default: 200000
        max_series_points:
          type: integer
          maximum: 200000
          minimum: 1
          title: Max Series Points
          default: 200000
        max_list_rows:
          type: integer
          maximum: 5000
          minimum: 1
          title: Max List Rows
          default: 5000
      additionalProperties: false
      type: object
      title: Caps
      description: Ceilings a plan may lower but never raise above the server maximums.
    Control:
      properties:
        label:
          anyOf:
            - type: string
              maxLength: 200
            - type: 'null'
          title: Label
        description:
          anyOf:
            - type: string
              maxLength: 500
            - type: 'null'
          title: Description
        options:
          anyOf:
            - items:
                anyOf:
                  - type: string
                  - type: integer
                  - type: number
                  - $ref: '#/components/schemas/ControlOption'
              type: array
              maxItems: 500
            - type: 'null'
          title: Options
        optionsFrom:
          anyOf:
            - $ref: '#/components/schemas/OptionsFrom'
            - type: 'null'
        min:
          anyOf:
            - type: number
            - type: 'null'
          title: Min
        max:
          anyOf:
            - type: number
            - type: 'null'
          title: Max
        step:
          anyOf:
            - type: number
            - type: 'null'
          title: Step
      additionalProperties: false
      type: object
      title: Control
    Filters:
      properties:
        ids:
          anyOf:
            - items:
                anyOf:
                  - type: string
                  - type: integer
                  - type: number
                  - type: boolean
                  - type: 'null'
              type: array
            - type: string
            - $ref: '#/components/schemas/StepRef'
            - type: 'null'
          title: Ids
        name:
          anyOf:
            - type: string
            - type: integer
            - type: number
            - type: boolean
            - type: 'null'
          title: Name
        nameContains:
          anyOf:
            - type: string
            - type: integer
            - type: number
            - type: boolean
            - type: 'null'
          title: Namecontains
        batch:
          anyOf:
            - type: string
            - type: integer
            - type: number
            - type: boolean
            - type: 'null'
          title: Batch
        measurementType:
          anyOf:
            - type: string
            - type: integer
            - type: number
            - type: boolean
            - type: 'null'
          title: Measurementtype
        analysisType:
          anyOf:
            - type: string
            - type: integer
            - type: number
            - type: boolean
            - type: 'null'
          title: Analysistype
        instanceIds:
          anyOf:
            - items:
                anyOf:
                  - type: string
                  - type: integer
                  - type: number
                  - type: boolean
                  - type: 'null'
              type: array
            - type: string
            - $ref: '#/components/schemas/StepRef'
            - type: 'null'
          title: Instanceids
        measurementIds:
          anyOf:
            - items:
                anyOf:
                  - type: string
                  - type: integer
                  - type: number
                  - type: boolean
                  - type: 'null'
              type: array
            - type: string
            - $ref: '#/components/schemas/StepRef'
            - type: 'null'
          title: Measurementids
        specificationIds:
          anyOf:
            - items:
                anyOf:
                  - type: string
                  - type: integer
                  - type: number
                  - type: boolean
                  - type: 'null'
              type: array
            - type: string
            - $ref: '#/components/schemas/StepRef'
            - type: 'null'
          title: Specificationids
        materialId:
          anyOf:
            - type: string
            - type: integer
            - type: number
            - type: boolean
            - type: 'null'
          title: Materialid
        studyId:
          anyOf:
            - type: string
            - type: integer
            - type: number
            - type: boolean
            - type: 'null'
          title: Studyid
      additionalProperties: false
      type: object
      title: Filters
      description: Filter keys a ``list`` step may use. Which apply depends on the source.
    StepRef:
      properties:
        from:
          type: string
          pattern: ^[A-Za-z_][A-Za-z0-9_]*$
          title: From
        column:
          type: string
          maxLength: 200
          title: Column
      additionalProperties: false
      type: object
      required:
        - from
        - column
      title: StepRef
      description: A column of an earlier row-shaped step, used as a list of values.
    Window:
      properties:
        min:
          anyOf:
            - type: number
            - type: string
            - type: 'null'
          title: Min
        max:
          anyOf:
            - type: number
            - type: string
            - type: 'null'
          title: Max
      additionalProperties: false
      type: object
      title: Window
    Metric:
      properties:
        fn:
          type: string
          enum:
            - first
            - last
            - min
            - max
            - mean
            - sum
            - count
            - first_where
            - last_where
          title: Fn
        column:
          anyOf:
            - type: string
              maxLength: 200
            - type: 'null'
          title: Column
        where:
          anyOf:
            - $ref: '#/components/schemas/Where'
            - type: 'null'
      additionalProperties: false
      type: object
      required:
        - fn
      title: Metric
    OptionsFrom:
      properties:
        step:
          type: string
          pattern: ^[A-Za-z_][A-Za-z0-9_]*$
          title: Step
        value:
          type: string
          maxLength: 200
          title: Value
        label:
          anyOf:
            - type: string
              maxLength: 200
            - type: 'null'
          title: Label
      additionalProperties: false
      type: object
      required:
        - step
        - value
      title: OptionsFrom
      description: >-
        Take a control's choices from a row-shaped step of the plan.


        The step is executed on its own (with its ancestors) whenever a figure
        is

        requested, so a record created after the recipe was written still
        appears.
    Where:
      properties:
        column:
          type: string
          maxLength: 200
          title: Column
        op:
          type: string
          enum:
            - lt
            - lte
            - gt
            - gte
            - eq
            - neq
          title: Op
        value:
          anyOf:
            - type: number
            - type: string
            - $ref: '#/components/schemas/RatioOf'
          title: Value
      additionalProperties: false
      type: object
      required:
        - column
        - op
        - value
      title: Where
      description: A comparison used inside ``first_where`` / ``last_where`` metrics.
    RatioOf:
      properties:
        ratio_of:
          type: string
          pattern: ^[A-Za-z_][A-Za-z0-9_]*$
          title: Ratio Of
        factor:
          anyOf:
            - type: number
            - type: string
          title: Factor
          description: A number or a $params reference.
      additionalProperties: false
      type: object
      required:
        - ratio_of
        - factor
      title: RatioOf
      description: >-
        ``factor × <another metric of the same group>``, for threshold
        comparisons.

````