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

# Get request status

> Read the state, result, billing, and error of a Mage API request from its status URL.

The request's state, result, and billing, in the same shape the submit call returned. Poll it until `status` is `completed`, `failed`, or `cancelled`; see [Requests and lifecycle](/api/requests) for the states and a polling strategy.

A completed request carries the output in `result`. Temporary media expires 30 days after the request (`result.expires_at`), so download what you want to keep. A failed request carries `error` and reports both the gems charged and the gems refunded.


## OpenAPI

````yaml api/openapi.json GET /v1/requests/{request_id}/status
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}/status:
    get:
      tags:
        - Requests
      summary: Get request status
      description: The state, result, and billing of a request.
      operationId: get_request_status
      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 current state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Request'
              examples:
                in_progress:
                  summary: Generating
                  value:
                    request_id: d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff
                    status: in_progress
                    architecture: flux2
                    model_id: flux2-dev
                    created_at: '2026-09-17T14:52:48.000Z'
                    updated_at: '2026-09-17T14:52:49.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
                completed:
                  summary: Completed
                  value:
                    request_id: d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff
                    status: completed
                    architecture: flux2
                    model_id: flux2-dev
                    created_at: '2026-09-17T14:52:48.000Z'
                    updated_at: '2026-09-17T14:53:10.000Z'
                    billing:
                      mode: gems
                      gems_charged: 40
                    result:
                      type: image
                      url: https://cdn3.mage.space/temp/30d/user/image.png
                      width: 1024
                      height: 1280
                      seed: 1234567
                      expires_at: '2026-10-17T14:52:48.000Z'
                      moderation:
                        nsfw: false
                    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
                failed:
                  summary: Failed and refunded
                  value:
                    request_id: d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff
                    status: failed
                    architecture: flux2
                    model_id: flux2-dev
                    created_at: '2026-09-17T14:52:48.000Z'
                    updated_at: '2026-09-17T14:53:02.000Z'
                    billing:
                      mode: gems
                      gems_charged: 40
                      gems_refunded: 40
                    result: null
                    error:
                      code: generation_failed
                      message: The generation failed. Any gems charged were refunded.
                    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'
        '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.

````