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

# Estimate a planned measurement's duration from its protocol

> Work out how long this planned test will take, before it runs.

Simulates the whole protocol with the cell specification's default model and
writes the total into ``estimated_duration_seconds`` -- the value scheduling
books channel windows off, which until now was always typed in by hand.

``buffer_pct`` pads the simulated figure by that percentage before booking it,
defaulting to ``DEFAULT_BUFFER_PCT``. A protocol whose duration is fixed by the
protocol alone is never padded.

Returns immediately with ``estimated_duration_status`` set to ``estimating``;
the job worker fills the duration in when the simulation finishes. Poll the
plan, or watch the status. When the simulation was already run for an
identical protocol and model, the estimate comes back ``ready`` instead.

For a test that has already started, use the cell measurement's
``estimate_end_time`` endpoint instead: that one replays the measured steps
and forecasts only what remains.



## OpenAPI

````yaml https://api.ionworks.com/openapi.json patch /projects/{project_id}/planned_measurements/{planned_measurement_id}/estimate_duration
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://api.ionworks.com
    description: Production
security: []
paths:
  /projects/{project_id}/planned_measurements/{planned_measurement_id}/estimate_duration:
    patch:
      tags:
        - Planned Measurements
      summary: Estimate a planned measurement's duration from its protocol
      description: >-
        Work out how long this planned test will take, before it runs.


        Simulates the whole protocol with the cell specification's default model
        and

        writes the total into ``estimated_duration_seconds`` -- the value
        scheduling

        books channel windows off, which until now was always typed in by hand.


        ``buffer_pct`` pads the simulated figure by that percentage before
        booking it,

        defaulting to ``DEFAULT_BUFFER_PCT``. A protocol whose duration is fixed
        by the

        protocol alone is never padded.


        Returns immediately with ``estimated_duration_status`` set to
        ``estimating``;

        the job worker fills the duration in when the simulation finishes. Poll
        the

        plan, or watch the status. When the simulation was already run for an

        identical protocol and model, the estimate comes back ``ready`` instead.


        For a test that has already started, use the cell measurement's

        ``estimate_end_time`` endpoint instead: that one replays the measured
        steps

        and forecasts only what remains.
      operationId: >-
        estimate_planned_measurement_duration_projects__project_id__planned_measurements__planned_measurement_id__estimate_duration_patch
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
            title: Project Id
        - name: planned_measurement_id
          in: path
          required: true
          schema:
            type: string
            title: Planned Measurement Id
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
                - $ref: '#/components/schemas/EstimateDurationRequest'
                - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlannedMeasurement'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    EstimateDurationRequest:
      properties:
        buffer_pct:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Buffer Pct
      type: object
      title: EstimateDurationRequest
      description: >-
        Options for a planned test's duration estimate.


        The body is optional on the endpoint; omitting it takes the default
        margin.
    PlannedMeasurement:
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
        cell_specification_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Cell Specification Id
          description: Cell specification the requester wants tested (set at request time).
        cell_instance_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Cell Instance Id
          description: Cell instance this future measurement will run on.
        channel_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Channel Id
          description: Channel reserved for this measurement, once scheduled.
        protocol_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Protocol Id
          description: >-
            Named protocol (experiment_template) this measurement will run.
            Required on create; a planned measurement must name a protocol.
        program_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Program Id
          description: >-
            Optional catalog program (Formation, Cycling, …) for this test
            request.
        test_setup:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Test Setup
          description: Planned physical setup.
        planned_start_time:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Planned Start Time
          description: When setup/run is planned to start.
        planned_end_time:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Planned End Time
          description: When this planned measurement is expected to release the channel.
        estimated_duration_seconds:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Estimated Duration Seconds
          description: Expected run duration before scheduled times exist.
        setup_duration_seconds:
          type: integer
          minimum: 0
          title: Setup Duration Seconds
          description: Operator setup duration before the test starts.
          default: 0
        teardown_duration_seconds:
          type: integer
          minimum: 0
          title: Teardown Duration Seconds
          description: Operator teardown duration after the test finishes.
          default: 0
        notes:
          anyOf:
            - type: string
            - type: 'null'
          title: Notes
          description: Free-text planning notes.
        id:
          type: string
          title: Id
        organization_id:
          type: string
          title: Organization Id
        project_id:
          type: string
          title: Project Id
        status:
          $ref: '#/components/schemas/PlannedMeasurementStatus'
        requested_by:
          type: string
          title: Requested By
        scheduled_by:
          anyOf:
            - type: string
            - type: 'null'
          title: Scheduled By
        scheduled_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Scheduled At
        started_measurement_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Started Measurement Id
        cancelled_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Cancelled At
        completed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Completed At
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        requested_by_email:
          anyOf:
            - type: string
            - type: 'null'
          title: Requested By Email
        scheduled_by_email:
          anyOf:
            - type: string
            - type: 'null'
          title: Scheduled By Email
        channel_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Channel Name
        cycler_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Cycler Id
        cycler_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Cycler Name
        program_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Program Name
        estimated_duration_status:
          anyOf:
            - $ref: '#/components/schemas/EstimationStatus'
            - type: 'null'
        estimated_duration_job_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Estimated Duration Job Id
        estimated_duration_simulation_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Estimated Duration Simulation Id
        simulated_duration_seconds:
          anyOf:
            - type: integer
            - type: 'null'
          title: Simulated Duration Seconds
        estimated_duration_is_exact:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Estimated Duration Is Exact
        estimated_duration_margin_pct:
          anyOf:
            - type: number
            - type: 'null'
          title: Estimated Duration Margin Pct
        actual_duration_seconds:
          anyOf:
            - type: integer
            - type: 'null'
          title: Actual Duration Seconds
        estimated_duration_note:
          anyOf:
            - type: string
            - type: 'null'
          title: Estimated Duration Note
        estimated_duration_calculated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Estimated Duration Calculated At
      type: object
      required:
        - name
        - id
        - organization_id
        - project_id
        - status
        - requested_by
        - created_at
        - updated_at
      title: PlannedMeasurement
      description: A planned measurement row returned by the API.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PlannedMeasurementStatus:
      type: string
      enum:
        - requested
        - scheduled
        - in_progress
        - completed
        - cancelled
      title: PlannedMeasurementStatus
      description: Lifecycle state for a planned measurement.
    EstimationStatus:
      type: string
      enum:
        - estimating
        - ready
        - failed
      title: EstimationStatus
      description: >-
        Lifecycle of a duration estimate computed by a background simulation.


        Used by both estimates: a planned test's total duration

        (``planned_measurements.estimated_duration_*``) and a running test's

        remaining duration (``cell_measurements.estimated_end_time_*``). One
        enum

        because the lifecycle is identical -- only what is being estimated
        differs.


        ``estimating`` while the job is in flight, ``ready`` once a value came
        from

        it, ``failed`` with the reason in the accompanying note. ``None`` means
        no

        estimate was ever requested.
    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

````