> ## Documentation Index
> Fetch the complete documentation index at: https://vastai-80aa3a82-fix-google-validation-docs-404s.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# show instance

> Retrieves the details of a specific instance for the authenticated user.

CLI Usage: `vastai show instance [--api-key <api_key>] [--raw]`



## OpenAPI

````yaml /api-reference/openapi.yaml get /api/v0/instances/{id}/
openapi: 3.1.0
info:
  title: Vast.ai API
  description: >-
    Vast.ai REST API for managing GPU cloud instances, machine operations, and
    AI/ML workflows.


    ## AI Agent Quick-Start


    Install the CLI skill for your agent (Claude Code, Cursor, Windsurf, etc.):
      npx skills add vast-ai/vast-cli

    CLI reference:
    https://raw.githubusercontent.com/vast-ai/vast-cli/master/vastai/SKILL.md

    SDK reference:
    https://raw.githubusercontent.com/vast-ai/vast-cli/master/vastai_sdk/SKILL.md


    ## Auth

    All endpoints require `Authorization: Bearer $VAST_API_KEY`.

    Get your key at: https://cloud.vast.ai/manage-keys/


    ## Key Quirks

    - `gpu_ram` in CLI = GB; in REST API = MB (CLI auto-converts)

    - SSH keys must be registered BEFORE creating an instance (VM: no recovery;
    Docker: can add post-create)

    - `onstart` field is limited to 4048 characters -- gzip+base64 for longer
    scripts

    - `POST /api/v0/asks/{id}/` (create instance) returns `new_contract` as the
    instance ID, not `id`

    - Poll trap: if `actual_status` becomes `exited`, `unknown`, or `offline` it
    will never reach `running` -- destroy and retry
  version: 1.0.0
  contact:
    name: Vast.ai Support
    url: https://discord.gg/vast
servers:
  - url: https://console.vast.ai
    description: Production server
security:
  - BearerAuth: []
paths:
  /api/v0/instances/{id}/:
    get:
      tags:
        - Instances
      summary: show instance
      description: |-
        Retrieves the details of a specific instance for the authenticated user.

        CLI Usage: `vastai show instance [--api-key <api_key>] [--raw]`
      parameters:
        - name: id
          in: path
          description: The instance (contract) ID to retrieve.
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Success response with instance details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  instances:
                    $ref: '#/components/schemas/Instance'
        '400':
          description: Bad Request – Invalid instance ID or invalid arguments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized – Invalid or missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                error: auth_error
                msg: Invalid user key
        '429':
          description: Too Many Requests – API requests are too frequent.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: API requests too frequent endpoint threshold=2.0
      security:
        - BearerAuth: []
components:
  schemas:
    Instance:
      type: object
      description: Detailed information about an instance.
      properties:
        id:
          type: integer
          description: Unique identifier for the instance.
          example: 883
        actual_status:
          type: string
          nullable: true
          description: Current status of the instance container.
          example: running
        intended_status:
          type: string
          description: Intended status of the instance container.
          example: running
        cur_state:
          type: string
          description: Current state of the machine contract.
          example: running
        next_state:
          type: string
          description: Next scheduled state for the machine contract.
          example: running
        label:
          type: string
          nullable: true
          description: User-defined label for the instance.
          example: null
        template_id:
          type: integer
          nullable: true
          description: Identifier for the instance template.
          example: null
        template_hash_id:
          type: string
          nullable: true
          description: Hash identifier for the instance template.
          example: null
        template_name:
          type: string
          nullable: true
          description: Name of the template (if available).
          example: null
        image_uuid:
          type: string
          description: Docker image used for the instance.
          example: tensorflow/tensorflow:latest-gpu
        image_args:
          type: array
          items:
            type: string
          description: Arguments passed to the container.
          example: []
        image_runtype:
          type: string
          description: How the container is launched (ssh, jupyter, etc.).
          example: ssh
        extra_env:
          type: array
          items:
            type: string
          description: Additional environment variables.
          example: []
        onstart:
          type: string
          nullable: true
          description: Script or command run at container start.
          example: null
        jupyter_token:
          type: string
          description: Jupyter token for the instance.
          example: 53fc448d6644aa7535c6fa5498cdbedc782753e88d81b44090e54dcf1332ed30
        status_msg:
          type: string
          nullable: true
          description: Status message for the instance.
          example: null
        local_ipaddrs:
          type: string
          description: Local IP addresses for the instance (space-separated).
          example: |
            10.2.202.31 172.17.0.1 
        ssh_host:
          type: string
          description: Host (or IP) used for SSH connection.
          example: ssh2281.vast.ai
        ssh_idx:
          type: string
          description: Identifier for the SSH forwarder used.
          example: '2281'
        ssh_port:
          type: integer
          description: Port used for SSH connection.
          example: 10882
        machine_dir_ssh_port:
          type: integer
          description: Calculated SSH port for accessing the machine directory.
          example: 5300
        machine_id:
          type: integer
          description: ID of the physical machine.
          example: 178
        bundle_id:
          type: integer
          description: ID of the bundle this instance belongs to.
          example: 617
        start_date:
          type: number
          format: float
          description: Instance start time (epoch seconds).
          example: 1761008618.225083
        end_date:
          type: number
          format: float
          description: Instance end time (epoch seconds).
          example: 2034617753
        uptime_mins:
          type: number
          nullable: true
          description: Uptime of the instance in minutes.
          example: null
        duration:
          type: number
          format: float
          description: Duration of the instance in seconds.
          example: 273608757.18784523
        cpu_arch:
          type: string
          description: CPU architecture.
          example: amd64
        cpu_cores:
          type: integer
          description: Number of CPU cores.
          example: 32
        cpu_cores_effective:
          type: number
          format: float
          description: Effective number of CPU cores allocated.
          example: 4
        cpu_name:
          type: string
          description: Name of the CPU.
          example: Xeon® Silver 4110
        cpu_ram:
          type: integer
          description: Total system RAM in MB.
          example: 128576
        cpu_util:
          type: number
          format: float
          description: CPU utilization as a fraction.
          example: 0
        mem_limit:
          type: number
          nullable: true
          description: Memory limit in megabytes.
          example: null
        mem_usage:
          type: number
          nullable: true
          description: Memory usage in megabytes.
          example: null
        vmem_usage:
          type: number
          nullable: true
          description: Virtual memory usage in megabytes.
          example: null
        gpu_name:
          type: string
          description: Name of the GPU.
          example: RTX A5000
        gpu_arch:
          type: string
          description: GPU architecture.
          example: nvidia
        gpu_totalram:
          type: integer
          description: Total GPU RAM in MB.
          example: 24564
        gpu_ram:
          type: integer
          description: Allocated GPU RAM in MB.
          example: 24564
        gpu_util:
          type: number
          nullable: true
          description: GPU utilization as a fraction.
          example: null
        gpu_temp:
          type: number
          nullable: true
          description: Current GPU temperature in Celsius.
          example: null
        gpu_frac:
          type: number
          format: float
          description: Fraction of GPU allocated.
          example: 0.125
        gpu_lanes:
          type: integer
          description: Number of PCIe lanes for the GPU.
          example: 16
        gpu_mem_bw:
          type: number
          format: float
          description: GPU memory bandwidth in GB/s.
          example: 628.8
        bw_nvlink:
          type: number
          format: float
          description: NVLink bandwidth in GB/s.
          example: 0
        disk_name:
          type: string
          description: Name of the disk.
          example: Samsung SSD 860
        disk_space:
          type: number
          format: float
          description: Disk space allocated in GB.
          example: 10
        disk_bw:
          type: number
          format: float
          description: Disk bandwidth in MB/s.
          example: 500.55
        disk_util:
          type: number
          format: float
          description: Disk utilization percentage.
          example: -1
        disk_usage:
          type: number
          format: float
          description: Disk usage percentage.
          example: -1
        direct_port_count:
          type: integer
          description: Number of direct ports available.
          example: 12
        direct_port_start:
          type: integer
          description: Start of direct port range.
          example: -1
        direct_port_end:
          type: integer
          description: End of direct port range.
          example: -1
        ports:
          type: array
          items:
            type: integer
          description: List of additional ports exposed by the instance.
          example:
            - 8080
            - 8081
        static_ip:
          type: boolean
          description: Whether the instance has a static public IP.
          example: true
        public_ipaddr:
          type: string
          description: Public IP address of the instance.
          example: 63.135.50.11
        geolocation:
          type: string
          description: Geographical location of the instance.
          example: Washington, US
        verification:
          type: string
          description: Verification status of the instance.
          example: verified
        rentable:
          type: boolean
          description: Whether the instance is currently rentable.
          example: true
        host_id:
          type: integer
          description: Host ID for the instance.
          example: 2
        hosting_type:
          type: integer
          description: Hosting type code.
          example: 1
        min_bid:
          type: number
          format: float
          description: Minimum bid price for the instance.
          example: 0.02
        is_bid:
          type: boolean
          description: Whether the instance was created via bidding.
          example: false
        dph_base:
          type: number
          format: float
          description: Base dollars per hour.
          example: 1
        dph_total:
          type: number
          format: float
          description: Total dollars per hour.
          example: 1.0020740740740741
        dlperf:
          type: number
          format: float
          description: Deep learning performance score.
          example: 22.229415
        dlperf_per_dphtotal:
          type: number
          format: float
          description: DLPerf per total DPH.
          example: 22.183404974866942
        flops_per_dphtotal:
          type: number
          format: float
          description: FLOPS per total DPH.
          example: 27.46814902424601
        total_flops:
          type: number
          format: float
          description: Total FLOPS.
          example: 27.52512
        score:
          type: number
          format: float
          description: Instance score.
          example: 22.043656178546772
        reliability2:
          type: number
          format: float
          description: Reliability score.
          example: 0.9993661
        os_version:
          type: string
          description: Operating system version.
          example: 18.04
        mobo_name:
          type: string
          description: Motherboard name.
          example: S7109GM2NR
        pci_gen:
          type: number
          format: float
          description: PCIe generation.
          example: 3
        pcie_bw:
          type: number
          format: float
          description: PCIe bandwidth in GB/s.
          example: 11.7
        num_gpus:
          type: integer
          description: Number of GPUs allocated.
          example: 1
        logo:
          type: string
          description: URL to the logo image.
          example: /static/logos/vastai_small2.png
        webpage:
          type: string
          nullable: true
          description: URL to the instance's webpage, if available.
          example: null
        search:
          type: object
          description: Search pricing details.
          example:
            gpuCostPerHour: 1
            diskHour: 0.002074074074074074
            totalHour: 1.0020740740740741
            discountTotalHour: 0
            discountedTotalPerHour: 1.0020740740740741
        instance:
          type: object
          description: Instance pricing details.
          example:
            gpuCostPerHour: 0
            diskHour: 0.002074074074074074
            totalHour: 0.002074074074074074
            discountTotalHour: 0
            discountedTotalPerHour: 0.002074074074074074
        storage_cost:
          type: number
          format: float
          description: Storage cost per hour.
          example: 0.14933333333333335
        storage_total_cost:
          type: number
          format: float
          description: Total storage cost.
          example: 0.002074074074074074
        vram_costperhour:
          type: number
          format: float
          description: VRAM cost per hour.
          example: 0.00004079441760601181
        credit_balance:
          type: number
          nullable: true
          description: User's credit balance.
          example: null
        credit_discount:
          type: number
          nullable: true
          description: User's credit discount.
          example: null
        credit_discount_max:
          type: number
          description: Maximum credit discount.
          example: 0.4
        client_run_time:
          type: number
          format: float
          description: Client run time in hours.
          example: 1.1
        host_run_time:
          type: number
          format: float
          description: Host run time in hours.
          example: 2592000
        external:
          type: boolean
          description: Whether the instance is external.
          example: false
        time_remaining:
          type: string
          description: Time remaining for the instance (if applicable).
          example: ''
        time_remaining_isbid:
          type: string
          description: Time remaining for the instance if it is a bid.
          example: ''
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
        msg:
          type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key must be provided in the Authorization header

````