# Python SDK Usage

<script
  type="application/ld+json"
  dangerouslySetInnerHTML={{
__html: JSON.stringify({
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "How to Use the Vast.ai Python SDK",
  "description": "A comprehensive guide to using the Vast.ai Python SDK including installation, basic usage, and examples for managing instances, SSH keys, file transfers, teams, and more.",
  "step": [
    {
      "@type": "HowToStep",
      "name": "Install the Python SDK",
      "text": "Install the latest stable PyPI release using pip: 'pip install vastai-sdk'. This will install the vastai-sdk package which provides convenient Python access to the Vast.ai API."
    },
    {
      "@type": "HowToStep",
      "name": "Import and Initialize the SDK",
      "text": "Import the VastAI class from the package: 'from vastai_sdk import VastAI'. Then construct a Vast client with your API key: 'vast_sdk = VastAI(api_key=\"YOUR_API_KEY\")'. This creates a client object that provides access to all Vast.ai resources."
    },
    {
      "@type": "HowToStep",
      "name": "Use Resource Methods",
      "text": "Call methods on the vast_sdk client object. Most CLI commands have equivalent methods. For example, 'vastai show instances' becomes 'vast_sdk.show_instances()'. IDEs will show type hints and available methods. Example: 'output = vast_sdk.show_instances(); print(output)'."
    },
    {
      "@type": "HowToStep",
      "name": "Manage Instances",
      "text": "Use instance management methods: 'vast_sdk.start_instance(ID=12345678)' to start, 'vast_sdk.stop_instance(ID=12345678)' to stop, 'vast_sdk.launch_instance(num_gpus=\"1\", gpu_name=\"RTX_3090\", image=\"pytorch/pytorch\")' to create new instances. Additional methods available for reboot, destroy, recycle, label, show details, and retrieve logs."
    },
    {
      "@type": "HowToStep",
      "name": "Perform Additional Operations",
      "text": "Use additional SDK features: Copy files with 'vast_sdk.copy(src=\"source_path\", dst=\"destination_path\", identity=\"identity_file\")'. Manage SSH keys with 'vast_sdk.create_ssh_key(ssh_key=\"your_ssh_key\")', 'vast_sdk.show_ssh_keys()', and 'vast_sdk.delete_ssh_key(ID=123456)'. Access API key management, autoscalers, endpoints, teams, host management, and more through respective methods."
    }
  ]
})
}}
/>

We provide a [PyPI package](https://pypi.org/project/vastai/), `vastai-sdk`, for convenient Python usage.

## PyPI Install

You can install the latest stable PyPI release with:

```text Text theme={null}
pip install vastai-sdk
```

## Usage

Import the package:

```text Text theme={null}
from vastai_sdk import VastAI
```

Construct a Vast client with your API key:

```text Text theme={null}
vast_sdk = VastAI(api_key='YOUR_API_KEY')
```

## Resource Methods

Most CLI commands have direct equivalents in the Python SDK. Your VastAI client exposes the same functionality through class methods and IDE's will surface type hints and arguments automatically.

For example, the CLI command `vastai show instances` has the equivalent, `vast_sdk.show_instances()`.

```text Text theme={null}
output = vast_sdk.show_instances()
print(output)
```

### Getting help

Use the built-in `help()` method to view detailed documentation for any SDK method. This will show you the method’s description, parameters, query syntax, and usage examples.

```text Text theme={null}
help(vast_sdk.search_offers)
```

## Example Usage

Here are some example usages of our Python SDK class `VastAI`:

### Search offers

Find an available RTX 3090 GPU

```text Text theme={null}
vast_sdk.search_offers(query='gpu_name=RTX_5090 rented=False rentable=True)
```

### Starting and Stopping Instances

```text Text theme={null}
vast_sdk.start_instance(ID=12345678)

vast_sdk.stop_instance(ID=12345678)
```

### Creating a New Instance

Create a new instance based on given parameters (performs search offers + create instance).

```text Text theme={null}
vast_sdk.launch_instance(num_gpus="1", gpu_name="RTX_3090", image="pytorch/pytorch")
```

### Copying Files Between Instances

```text Text theme={null}
vast_sdk.copy(src='source_path', dst='destination_path', identity='identity_file')
```

### Managing SSH Keys

Create a new SSH key, show all SSH keys, and delete an SSH key.

```text Text   theme={null}
vast_sdk.create_ssh_key(ssh_key='your_ssh_key')

ssh_keys = vast_sdk.show_ssh_keys()
print(ssh_keys)

vast_sdk.delete_ssh_key(ID=123456)
```

## Contribution and Issue Reporting

This [code repository](https://github.com/vast-ai/vast-python) is open source and can be rapidly changing at times. If you find a potential bug, please open an issue on GitHub. If you wish to contribute to improving this code and its functionality, feel welcome to open a PR with any improvements on our [GitHub repository](https://github.com/vast-ai/vast-python).

## Available Methods

Below is a list of the available methods you can call on the `VastAI` client. These methods are categorized for better readability.

### Instance Management

| Method                                               | Description                                    |
| ---------------------------------------------------- | ---------------------------------------------- |
| `start_instance(ID: int)`                            | Start an instance.                             |
| `stop_instance(ID: int)`                             | Stop an instance.                              |
| `reboot_instance(ID: int)`                           | Reboot an instance.                            |
| `destroy_instance(id: int)`                          | Destroy an instance.                           |
| `destroy_instances(ids: List[int])`                  | Destroy multiple instances.                    |
| `recycle_instance(ID: int)`                          | Recycle an instance.                           |
| `label_instance(id: int, label: str)`                | Label an instance.                             |
| `show_instance(id: int)`                             | Show details of an instance.                   |
| `show_instances(quiet: bool = False)`                | Show all instances.                            |
| `logs(INSTANCE_ID: int, tail: Optional[str] = None)` | Retrieve logs for an instance.                 |
| `execute(ID: int, COMMAND: str)`                     | Execute a command on an instance.              |
| `launch_instance(...)`                               | Launch a new instance with various parameters. |

### SSH Key Management

| Method                                          | Description                         |
| ----------------------------------------------- | ----------------------------------- |
| `create_ssh_key(ssh_key: str)`                  | Create a new SSH key.               |
| `delete_ssh_key(ID: int)`                       | Delete an SSH key.                  |
| `show_ssh_keys()`                               | Show all SSH keys.                  |
| `attach_ssh(instance_id: int, ssh_key: str)`    | Attach an SSH key to an instance.   |
| `detach_ssh(instance_id: int, ssh_key_id: str)` | Detach an SSH key from an instance. |

### API Key Management

| Method                                            | Description                 |
| ------------------------------------------------- | --------------------------- |
| `create_api_key(name: Optional[str] = None, ...)` | Create a new API key.       |
| `delete_api_key(ID: int)`                         | Delete an API key.          |
| `reset_api_key()`                                 | Reset the API key.          |
| `show_api_key(id: int)`                           | Show details of an API key. |
| `show_api_keys()`                                 | Show all API keys.          |
| `set_api_key(new_api_key: str)`                   | Set a new API key.          |

### Autoscaler Management

| Method                                                              | Description              |
| ------------------------------------------------------------------- | ------------------------ |
| `create_autoscaler(test_workers: int = 3, ...)`                     | Create a new autoscaler. |
| `update_autoscaler(ID: int, min_load: Optional[float] = None, ...)` | Update an autoscaler.    |
| `delete_autoscaler(ID: int)`                                        | Delete an autoscaler.    |
| `show_autoscalers()`                                                | Show all autoscalers.    |

### Endpoint Management

| Method                                                            | Description            |
| ----------------------------------------------------------------- | ---------------------- |
| `create_endpoint(min_load: float = 0.0, ...)`                     | Create a new endpoint. |
| `update_endpoint(ID: int, min_load: Optional[float] = None, ...)` | Update an endpoint.    |
| `delete_endpoint(ID: int)`                                        | Delete an endpoint.    |
| `show_endpoints()`                                                | Show all endpoints.    |

### File Management

| Method                                                                          | Description                                                 |
| ------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `copy(src: str, dst: str, identity: Optional[str] = None)`                      | Copy files between instances.                               |
| `cloud_copy(src: Optional[str] = None, dst: Optional[str] = "/workspace", ...)` | Copy files between cloud and instance.                      |
| `cancel_copy(dst: str)`                                                         | Cancel a file copy operation.                               |
| `cancel_sync(dst: str)`                                                         | Cancel a file sync operation.                               |
| `scp_url(id: int)`                                                              | Get the SCP URL for transferring files to/from an instance. |

### Team Management

| Method                                                                                     | Description                           |
| ------------------------------------------------------------------------------------------ | ------------------------------------- |
| `create_team(team_name: Optional[str] = None)`                                             | Create a new team.                    |
| `destroy_team()`                                                                           | Destroy a team.                       |
| `invite_team_member(email: Optional[str] = None, role: Optional[str] = None)`              | Invite a new member to the team.      |
| `remove_team_member(ID: int)`                                                              | Remove a member from the team.        |
| `create_team_role(name: Optional[str] = None, permissions: Optional[str] = None)`          | Create a new team role.               |
| `remove_team_role(NAME: str)`                                                              | Remove a role from the team.          |
| `update_team_role(ID: int, name: Optional[str] = None, permissions: Optional[str] = None)` | Update details of a team role.        |
| `show_team_members()`                                                                      | Show all team members.                |
| `show_team_role(NAME: str)`                                                                | Show details of a specific team role. |
| `show_team_roles()`                                                                        | Show all team roles.                  |

### Host Management

| Method                                                                                                                                                                                                                                                                                   | Description                                                                           |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `cleanup_machine(ID: int)`                                                                                                                                                                                                                                                               | Clean up a machine's configuration and resources.                                     |
| `list_machine(ID: int, price_gpu: Optional[float] = None, price_disk: Optional[float] = None, price_inetu: Optional[float] = None, price_inetd: Optional[float] = None, discount_rate: Optional[float] = None, min_chunk: Optional[int] = None, end_date: Optional[str] = None)`         | List details of a single machine with optional pricing and configuration parameters.  |
| `list_machines(IDs: List[int], price_gpu: Optional[float] = None, price_disk: Optional[float] = None, price_inetu: Optional[float] = None, price_inetd: Optional[float] = None, discount_rate: Optional[float] = None, min_chunk: Optional[int] = None, end_date: Optional[str] = None)` | List details of multiple machines with optional pricing and configuration parameters. |
| `remove_defjob(id: int)`                                                                                                                                                                                                                                                                 | Remove the default job from a machine.                                                |
| `set_defjob(id: int, price_gpu: Optional[float] = None, price_inetu: Optional[float] = None, price_inetd: Optional[float] = None, image: Optional[str] = None, args: Optional[List[str]] = None)`                                                                                        | Set a default job on a machine with specified parameters.                             |
| `set_min_bid(id: int, price: Optional[float] = None)`                                                                                                                                                                                                                                    | Set the minimum bid price for a machine.                                              |
| `schedule_maint(id: int, sdate: Optional[float] = None, duration: Optional[float] = None)`                                                                                                                                                                                               | Schedule maintenance for a machine.                                                   |
| `cancel_maint(id: int)`                                                                                                                                                                                                                                                                  | Cancel scheduled maintenance for a machine.                                           |
| `unlist_machine(id: int)`                                                                                                                                                                                                                                                                | Unlist a machine from being available for new jobs.                                   |
| `show_machines(quiet: bool = False, filter: Optional[str] = None)`                                                                                                                                                                                                                       | Retrieve and display a list of machines based on specified criteria.                  |

### Other Methods

| Method                                                                                                                                                                 | Description                                      |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `get_gpu_names()`                                                                                                                                                      | Returns a set of GPU names available on Vast.ai. |
| `show_connections()`                                                                                                                                                   | Show all connections.                            |
| `show_deposit(ID: int)`                                                                                                                                                | Show deposit details for an instance.            |
| `show_earnings(quiet: bool = False, start_date: Optional[str] = None, end_date: Optional[str] = None, machine_id: Optional[int] = None)`                               | Show earnings information.                       |
| `show_invoices(quiet: bool = False, start_date: Optional[str] = None, end_date: Optional[str] = None, ...)`                                                            | Show invoice details.                            |
| `show_ipaddrs()`                                                                                                                                                       | Show IP addresses.                               |
| `show_user(quiet: bool = False)`                                                                                                                                       | Show user details.                               |
| `show_subaccounts(quiet: bool = False)`                                                                                                                                | Show all subaccounts of the current user.        |
| `transfer_credit(recipient: str, amount: float)`                                                                                                                       | Transfer credit to another account.              |
| `update_ssh_key(id: int, ssh_key: str)`                                                                                                                                | Update an SSH key.                               |
| `generate_pdf_invoices(quiet: bool = False, start_date: Optional[str] = None, end_date: Optional[str] = None, only_charges: bool = False, only_credits: bool = False)` | Generate PDF invoices based on filters.          |

For a complete list of methods and their usage, please refer to [Commands](https://docs.vast.ai/cli/commands).


---

> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://docs.vast.ai/llms.txt