> ## Documentation Index > Fetch the complete documentation index at: https://docs.infery.ai/llms.txt > Use this file to discover all available pages before exploring further. # Cancel a run > POST /v1/workflows/runs/{id}/cancel Best-effort. A step already in flight with a provider is not clawed back — the run stops at the next boundary it can, and the work already done is still charged. ## OpenAPI ````yaml openapi.json POST /v1/workflows/runs/{id}/cancel openapi: 3.0.0 info: title: Infery Gateway description: >- Infery Inference Gateway — OpenAI-compatible API for LLMs, embeddings, images, audio, and video version: '1.0' contact: {} servers: - url: https://api.infery.ai description: Production - url: http://localhost:3001 description: Local security: [] tags: [] paths: /v1/workflows/runs/{id}/cancel: post: tags: - Workflows summary: Best-effort cancel of a running or queued workflow run description: >- Takes no request body. Sets a cancellation flag the runner checks BETWEEN steps, closes any step row still `running`, removes the job from the queue if it has not started, and recurses into in-flight child runs. BEST-EFFORT, and what that costs: a step already dispatched runs to completion and is billed, and it may settle `succeeded` after the cancel — a cancelled run truthfully containing a succeeded step is not a bug. Nothing already settled is refunded. Idempotent: cancelling a run that has already ended is a no-op that echoes the status it already had, so a `succeeded` in the response means the run beat the cancel. ACCESS: whoever may START this run may stop it — the workflow it belongs to must be visible to this caller, the same rule `POST /v1/workflows/runs` applies to that workflow. Deliberately NOT the reads' rule below: a share of the RUN discloses that run's results and does not carry cancellation, so a caller who can read a run this way still gets a 404 here. A run of an inline definition, or of a workflow that has since been deleted, belongs to no workflow the rule could apply to, and the workspace scope of the key is the whole rule for it. operationId: PipelineRunsController_cancel[0] parameters: - name: id required: true in: path description: Run UUID. schema: example: 3c9a7e51-8b24-4f0d-9a17-6e2b5c4d8a03 type: string responses: '201': description: >- The run's status after the call — `cancelled`, or the terminal status it already had. content: application/json: schema: $ref: '#/components/schemas/CancelRunResultDto' '401': description: Unauthorized — invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' '404': description: >- No run with this id in this workspace, or its workflow is not visible to this caller — deliberately the same answer. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' security: - ApiKey: [] components: schemas: CancelRunResultDto: type: object properties: id: type: string description: The run the cancel was addressed to. example: 3c9a7e51-8b24-4f0d-9a17-6e2b5c4d8a03 status: type: string enum: - succeeded - failed - cancelled description: >- `cancelled` when this call moved the run. For a run that was ALREADY terminal the call is a no-op and this echoes the status it already had — so a `succeeded` here means the run finished before the cancel reached it, not that cancelling succeeded. example: cancelled required: - id - status ErrorResponseDto: type: object properties: error: description: >- The error envelope. Every non-2xx response from this API has this shape, so a client can parse failures without branching on the endpoint. allOf: - $ref: '#/components/schemas/ErrorDetailDto' required: - error ErrorDetailDto: type: object properties: message: type: string example: Model not found description: Human-readable error message type: type: string example: invalid_request_error description: Error category enum: - invalid_request_error - authentication_error - permission_error - quota_exceeded - rate_limit_error - server_error code: type: string example: model_not_found nullable: true description: >- Stable machine-readable error code. Branch on this rather than on `message`, which is prose and may be reworded. param: type: string example: model nullable: true description: >- Name of the request parameter that triggered the error. `null` when the error is not attributable to one field. job_id: type: string example: job_1hR9xTPZqK4mVLc2nJ7fY5wB description: >- Handle to work that is ALREADY RUNNING AND ALREADY BILLED, present on the few errors that carry one. When it is here, this is not a failure to retry — retrying pays twice. Collect the result from `GET /v1/images/jobs/{job_id}`, which serves every durable media job regardless of modality. Two situations produce it. A media generation that outruns the gateway's wait answers `504` with `code: "job_timeout"` and keeps working. And `POST /v1/audio/speech` answers **500** with `code: "artifact_unreadable"` when the speech was generated and settled but could not be read back from storage — the audio exists and is paid for; only this response failed. Declared here rather than per-endpoint because the rule is about the FIELD, not the status: if this is present, there is a paid-for result to collect. It was undeclared until now, so a client generated from this document could not see the one field that recovers money already spent. required: - message - type - code - param securitySchemes: ApiKey: type: apiKey in: header name: Authorization description: 'API key in format: Bearer inf_***' ````