> ## Documentation Index > Fetch the complete documentation index at: https://docs.mage.space/llms.txt > Use this file to discover all available pages before exploring further. # Cancel request > Stop a live Mage API request through its cancel URL. Gems are not refunded on cancellation. Stop a live request. The run is marked cancelled and the generation backend is asked to stop; the response is the request's state afterwards. Gems are not returned on cancellation, as in the web app. Cancelling a request that already finished is a `409 request_finished`. Cancelling one that is already cancelled does nothing and returns its state. ## OpenAPI ````yaml api/openapi.json POST /v1/requests/{request_id}/cancel openapi: 3.1.0 info: title: Mage API version: v1 description: >- Run Mage models from your own code: submit a generation, poll its status, download the result. Every request is paid in gems. contact: name: Mage url: https://www.mage.space email: mage@mage.space servers: - url: https://api.mage.space description: Production security: - apiKey: [] tags: - name: Requests description: Submit, poll, and cancel generations. - name: Catalog description: What the API can generate with. - name: Account description: The gems balance. - name: Uploads description: Large input files. - name: Image models description: One endpoint per image architecture. - name: Video models description: One endpoint per video architecture. paths: /v1/requests/{request_id}/cancel: post: tags: - Requests summary: Cancel request description: Stop a live request. Gems are not refunded. operationId: cancel_request parameters: - name: request_id in: path required: true description: The `request_id` from the submit response. schema: type: string format: uuid responses: '200': description: The request's state after the cancellation. content: application/json: schema: $ref: '#/components/schemas/Request' example: request_id: d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff status: cancelled architecture: flux2 model_id: flux2-dev created_at: '2026-09-17T14:52:48.000Z' updated_at: '2026-09-17T14:52:55.000Z' billing: mode: gems gems_charged: 40 result: null error: null status_url: >- https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status cancel_url: >- https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/RequestNotFound' '409': description: The request already finished. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: request_finished message: The request has already finished and cannot be cancelled. '500': $ref: '#/components/responses/InternalError' components: schemas: Request: type: object properties: request_id: type: string format: uuid description: The request id, also the id in `status_url` and `cancel_url`. status: type: string enum: - queued - in_progress - completed - failed - cancelled description: >- `queued` and `in_progress` are live; `completed`, `failed`, and `cancelled` are final. architecture: type: string description: The architecture the request generates with. model_id: anyOf: - type: string - type: 'null' description: The model variant, when the architecture has variants. created_at: type: string format: date-time description: When the request was accepted. updated_at: type: string format: date-time description: When the request last changed. billing: type: object properties: mode: type: string const: gems description: Every API request is paid in gems. gems_charged: type: number description: Gems debited for the request. gems_refunded: description: Gems returned to the account; present on failed requests. type: number required: - mode - gems_charged additionalProperties: false result: anyOf: - type: object properties: type: type: string enum: - image - video - audio description: The media type of the output. url: type: string format: uri description: Where to download the output. width: type: integer description: Output width in pixels. height: type: integer description: Output height in pixels. seed: type: integer description: The seed the generation ran with. expires_at: anyOf: - type: string format: date-time - type: 'null' description: >- When `url` stops working: 30 days after the request for temporary media, or null for permanent media. moderation: type: object properties: nsfw: type: boolean description: Whether moderation flagged the output as NSFW. required: - nsfw additionalProperties: false description: Moderation flags on the output. required: - type - url - width - height - seed - expires_at - moderation additionalProperties: false - type: 'null' description: The output once `status` is `completed`, else null. error: anyOf: - type: object properties: code: type: string enum: - unauthorized - invalid_request - invalid_config - architecture_not_found - architecture_retired - request_not_found - not_found - insufficient_gems - forbidden - content_blocked - request_finished - too_many_requests - generation_failed - internal_error description: A stable error code. message: type: string description: What went wrong, for a person. required: - code - message additionalProperties: false - type: 'null' description: Why the request failed once `status` is `failed`, else null. status_url: type: string format: uri description: Poll this URL for the request. cancel_url: type: string format: uri description: POST to this URL to stop the request. required: - request_id - status - architecture - model_id - created_at - updated_at - billing - result - error - status_url - cancel_url additionalProperties: false Error: type: object properties: error: type: object properties: code: type: string enum: - unauthorized - invalid_request - invalid_config - architecture_not_found - architecture_retired - request_not_found - not_found - insufficient_gems - forbidden - content_blocked - request_finished - too_many_requests - generation_failed - internal_error description: A stable error code; treat an unknown code by its HTTP status. message: type: string description: What went wrong, for a person. request_id: description: >- The request the refusal belongs to, when one was recorded before the refusal. type: string format: uuid gems_required: description: The price of the refused generation, on `insufficient_gems`. type: number docs_url: description: Where to read the API reference, on `not_found`. type: string format: uri required: - code - message additionalProperties: true description: Further fields depend on the code. required: - error additionalProperties: false responses: Unauthorized: description: The key is missing, malformed, unknown, or revoked. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: unauthorized message: The API key is invalid or has been revoked. RequestNotFound: description: >- No request with this id belongs to the account, or it was not made through the API. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: request_not_found message: No request with this id belongs to the account. InternalError: description: >- Something failed on Mage's side. Retry, and contact support if it persists. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: internal_error message: >- Something went wrong on our side. Retry, and contact support if it persists. securitySchemes: apiKey: type: http scheme: bearer description: >- An API key from Settings → API, sent as `Authorization: Bearer mage_sk_…`. Keys are for server-side code only. ````