> ## Documentation Index > Fetch the complete documentation index at: https://docs.sagescreen.dev/llms.txt > Use this file to discover all available pages before exploring further. # End a run > Gracefully ends the run. If the current step is the last step, it is finished and the run state is set to `finished`. If the run ends before the last step, remaining steps are failed and the run state is `failed`. ## OpenAPI ````yaml /openapi/private/specs/services/workflow.yml get /workflow/run/{run_id}/end openapi: 3.1.0 info: title: Workflow Service API description: > Manages workflow runs and step-by-step state machine execution. Workflows are used to orchestrate multi-step processes like sage culture generation. ## Authentication All endpoints require authentication via API key: - **API Key**: Pass the key in the `X-Auth` header (service-to-service calls) ## Workflow Model - **Workflow Steps** (templates) define the step sequence for a workflow `type` - **Runs** are instances of a workflow type, tracking state and progress - **Run Steps** are materialized copies of template steps for each run ## State Machine ### Run States - `queued` -- created but not yet started - `running` -- actively progressing through steps - `finished` -- all steps completed successfully - `failed` -- a step failed or was executed out of order - `canceled` -- manually cancelled ### Step States - `pending` -- waiting to start - `running` -- actively executing - `finished` -- completed successfully - `failed` -- execution failed ## Business Rules - Steps must be executed in order; out-of-order transitions fail the entire run - A run cannot be transitioned if already finished, failed, or cancelled - Only one step can be running at a time - Cancelling a run fails all pending/running steps - The response `meta` object includes `steps`, `current_step`, `next_step`, `previous_step`, `first_step`, and `last_step` navigation aids version: 1.0.0 contact: name: Platform Team servers: - url: '{protocol}://{host}:{port}' description: Workflow Service variables: protocol: default: https enum: - http - https host: default: localhost port: default: '5000' security: [] tags: - name: Workflow description: Workflow run management and step transitions - name: Service description: Health checks and initialization paths: /workflow/run/{run_id}/end: get: tags: - Workflow summary: End a run description: | Gracefully ends the run. If the current step is the last step, it is finished and the run state is set to `finished`. If the run ends before the last step, remaining steps are failed and the run state is `failed`. operationId: endRun parameters: - $ref: '#/components/parameters/RunId' - $ref: '#/components/parameters/RequiredPermission_valid' responses: '200': description: Run ended content: application/json: schema: $ref: '#/components/schemas/WorkflowRunWithMeta' '400': description: Invalid state content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: runAlreadyFinished: summary: Run already finished value: error: Run already finished runFailed: summary: Run already failed value: error: Run failed runCanceled: summary: Run was cancelled value: error: Run canceled '401': $ref: '#/components/responses/Unauthorized' '404': description: Run not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Run not found '500': $ref: '#/components/responses/InternalError' security: - apiKeyAuth: [] components: parameters: RunId: name: run_id in: path required: true description: UUID of the workflow run schema: type: string format: uuid example: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d RequiredPermission_valid: name: X-Permission-Info in: header required: false description: >- **Required API key permission: `valid`** (informational only -- enforced server-side) schema: type: string schemas: WorkflowRunWithMeta: allOf: - $ref: '#/components/schemas/WorkflowRun' - type: object properties: meta: type: object description: Navigation metadata for the run properties: steps: type: array items: $ref: '#/components/schemas/WorkflowRunStep' description: All steps in the run current_step: $ref: '#/components/schemas/WorkflowRunStep' next_step: $ref: '#/components/schemas/WorkflowRunStep' previous_step: $ref: '#/components/schemas/WorkflowRunStep' first_step: $ref: '#/components/schemas/WorkflowRunStep' last_step: $ref: '#/components/schemas/WorkflowRunStep' ErrorResponse: type: object required: - error properties: error: type: string description: Human-readable error message WorkflowRun: type: object description: Workflow run record (from WorkflowRunModel.to_dict()) properties: id: type: string format: uuid description: Run UUID type: type: string description: Workflow type (e.g., `sage`, `sage-nc`) state: $ref: '#/components/schemas/RunStateEnum' percent: type: integer minimum: 0 maximum: 100 description: Progress percentage current_step: type: - string - 'null' description: ID of the currently running step (null when ended) started_at: type: string format: date-time description: When the run was created ended_at: type: - string - 'null' format: date-time description: When the run ended (null if still running) duration_ms: type: - integer - 'null' description: Total run duration in milliseconds number_of_steps: type: integer description: Total number of steps in this run result: type: - object - 'null' description: Run result data errors: type: - object - 'null' description: 'Error details (e.g., `{"message": "Run canceled"}`)' WorkflowRunStep: type: object description: Materialized step for a run (from WorkflowRunStepModel.to_dict()) properties: id: type: string format: uuid description: Step UUID run_id: type: string format: uuid description: Parent run UUID name: type: string description: Step name (e.g., `creating_sage`, `reading_context`) step_order: type: integer description: Position in sequence (0-indexed) state: $ref: '#/components/schemas/StepStateEnum' timing_avg_ms: type: - integer - 'null' description: Average expected duration (from template) timing_min_ms: type: - integer - 'null' description: Minimum expected duration timing_max_ms: type: - integer - 'null' description: Maximum expected duration label: type: - array - 'null' items: type: string description: Display labels for the step started_at: type: - string - 'null' format: date-time description: When the step started ended_at: type: - string - 'null' format: date-time description: When the step ended duration_ms: type: - integer - 'null' description: Actual duration in milliseconds number_of_steps: type: integer description: Total steps in the parent run current_duration: type: number description: Elapsed time in ms (only present when state is `running`) RunStateEnum: type: string enum: - queued - running - finished - failed - canceled description: | Current state of the workflow run: - `queued` -- created but not yet started - `running` -- actively executing steps - `finished` -- all steps completed successfully - `failed` -- a step failed or out-of-order transition - `canceled` -- manually cancelled StepStateEnum: type: string enum: - pending - running - finished - failed description: | Current state of a workflow step: - `pending` -- waiting to start - `running` -- actively executing - `finished` -- completed successfully - `failed` -- execution failed responses: Unauthorized: description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: noApiKey: summary: Missing API key value: error: Unauthorized - API key required invalidApiKey: summary: Invalid API key value: error: Unauthorized - Invalid API key InternalError: description: Unexpected server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Internal server error securitySchemes: apiKeyAuth: type: apiKey in: header name: X-Auth description: Service-to-service API key ````