> ## Documentation Index
> Fetch the complete documentation index at: https://vastai-80aa3a82-auto-openapi-update-8483c1e9.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Execute Instance Command

> Runs a whitelisted command on a stopped instance's container and returns a URL where the output can be retrieved.



## OpenAPI

````yaml /api-reference/openapi.yaml put /api/v0/instances/command/{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/command/{id}/:
    put:
      tags:
        - Instances
      summary: Execute Instance Command
      description: >-
        Runs a whitelisted command on a stopped instance's container and returns
        a URL where the output can be retrieved.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: ID of the instance to execute command on
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                command:
                  type: string
                  description: Command to execute on the instance
                  example: ls -l
      responses:
        '200':
          description: >-
            Returns {success: true, writeable_path, result_url, msg: "Command is
            executing, wait a few seconds and then view the result_url"}.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: True when command was queued
                  writeable_path:
                    type: string
                    description: Filesystem path writable by the container
                  result_url:
                    type: string
                    description: URL to poll for command output
                  msg:
                    type: string
                    description: Human-readable status message
        '400':
          description: >-
            Returns {error: "invalid_args"} with messages such as "Missing
            instance ID", "Invalid instance_id.", "Missing command.", "Invalid
            command.", "Invalid command given.", "Container not ready", "Execute
            command only avail on stopped instances. Use ssh to run commands on
            running instances.", or "VM instances do not support this
            operation."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: >-
            Returns {error: "not_found", msg: "Instance not found."} when the
            instance doesn't exist for the user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - BearerAuth: []
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
        msg:
          type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key must be provided in the Authorization header

````