# Volume (/docs/python-sdk/volume)

## SandboxVolumesService [#sandboxvolumesservice]

```python
class SandboxVolumesService()
```

Pull attached volumes, separate from the root platform volume service.

#### SandboxVolumesService.\_\_init\_\_ [#sandboxvolumesservice__init__]

```python
def __init__(impl: AsyncSandboxVolumesService, bridge: SyncBridge) -> None
```

#### SandboxVolumesService.pull [#sandboxvolumesservicepull]

```python
def pull(volume_id: str,
         *,
         request_id: str,
         timeout: Optional[float] = None) -> PullVolumeResult
```

Submit/check once; timeout is a server wait in seconds (0–30, default 30).

## AsyncSandboxVolumesService [#asyncsandboxvolumesservice]

```python
class AsyncSandboxVolumesService()
```

Pull attached volumes, separate from the root platform volume service.

#### AsyncSandboxVolumesService.\_\_init\_\_ [#asyncsandboxvolumesservice__init__]

```python
def __init__(transport: AsyncTransport) -> None
```

#### AsyncSandboxVolumesService.pull [#asyncsandboxvolumesservicepull]

```python
async def pull(volume_id: str,
               *,
               request_id: str,
               timeout: Optional[float] = None) -> PullVolumeResult
```

Submit/check once; timeout is a server wait in seconds (0–30, default 30).

Zero does not wait: it submits a new request_id, or returns a known one's
last outcome without retrying it; a timeout above zero retries pending,
unavailable or rate-limited work. Expiry does not cancel work. Neither
retries nor identities are automatic.

## VolumeService [#volumeservice]

```python
class VolumeService()
```

Persistent volume namespace.

#### VolumeService.\_\_init\_\_ [#volumeservice__init__]

```python
def __init__(impl: AsyncVolumeService, bridge: SyncBridge) -> None
```

#### VolumeService.create [#volumeservicecreate]

```python
def create(*, name: str, size_gib: Optional[int] = None) -> VolumeDto
```

Create a volume.

#### VolumeService.delete [#volumeservicedelete]

```python
def delete(volume_id: str, *, id_only: bool = False) -> None
```

Request deletion and return once the control plane accepts it.

#### VolumeService.get [#volumeserviceget]

```python
def get(name_or_id: str, *, create: bool = False, id_only: bool = False) -> VolumeDto
```

Fetch by id or name; `id_only` disables name fallback.

#### VolumeService.iter [#volumeserviceiter]

```python
def iter(*,
         cursor: Optional[str] = None,
         limit: Optional[int] = None) -> Iterator[VolumeDto]
```

#### VolumeService.list [#volumeservicelist]

```python
def list(*,
         cursor: Optional[str] = None,
         limit: Optional[int] = None) -> ListResult[VolumeDto]
```

List volumes.

## AsyncVolumeService [#asyncvolumeservice]

```python
class AsyncVolumeService()
```

Persistent volume namespace.

#### AsyncVolumeService.\_\_init\_\_ [#asyncvolumeservice__init__]

```python
def __init__(transport: AsyncTransport) -> None
```

#### AsyncVolumeService.list [#asyncvolumeservicelist]

```python
async def list(*,
               cursor: Optional[str] = None,
               limit: Optional[int] = None) -> ListResult[VolumeDto]
```

List volumes.

#### AsyncVolumeService.iter [#asyncvolumeserviceiter]

```python
async def iter(*,
               cursor: Optional[str] = None,
               limit: Optional[int] = None) -> AsyncIterator[VolumeDto]
```

#### AsyncVolumeService.get [#asyncvolumeserviceget]

```python
async def get(name_or_id: str,
              *,
              create: bool = False,
              id_only: bool = False) -> VolumeDto
```

Fetch by id or name; `id_only` disables name fallback.

#### AsyncVolumeService.create [#asyncvolumeservicecreate]

```python
async def create(*, name: str, size_gib: Optional[int] = None) -> VolumeDto
```

Create a volume.

#### AsyncVolumeService.delete [#asyncvolumeservicedelete]

```python
async def delete(volume_id: str, *, id_only: bool = False) -> None
```

Request deletion and return once the control plane accepts it.

## PullVolumeResult [#pullvolumeresult]

```python
@dataclass(frozen=True)
class PullVolumeResult()
```

**Attributes**:

- `request_id` _str_
- `status` _PullVolumeStatus_
- `manifest_id` _Optional\[str\]_
- `raw_status` _Optional\[str\] = None_

## VolumeMount [#volumemount]

```python
@dataclass(frozen=True)
class VolumeMount()
```

Attach a persistent volume to a sandbox.

**Attributes**:

- `volume_id` _str_
- `mount_path` _str_
- `subpath` _Optional\[str\] = None_
- `read_only` _Optional\[bool\] = None_

## VolumeDto [#volumedto]

```python
@dataclass(frozen=True, slots=True)
class VolumeDto()
```

**Attributes**:

- `id` _str_
- `name` _str_
- `type` _VolumeType_
- `raw_type` _str_
- `status` _VolumeState_
- `raw_status` _str_
- `created_at` _datetime_
- `updated_at` _datetime_
- `size_gib` _Optional\[int\] = None_
- `error` _Optional\[str\] = None_
- `last_used_at` _Optional\[datetime\] = None_
- `options` _Optional\[JsonObject\] = None_
- `used_bytes` _Optional\[int\] = None_
- `used_bytes_at` _Optional\[datetime\] = None_

## PullVolumeStatus [#pullvolumestatus]

```python
PullVolumeStatus = Literal['pulled', 'unchanged', 'pending', 'unknown']
```

## VolumeState [#volumestate]

```python
VolumeState = Literal['ready', 'deleting', 'deleted', 'error', 'unknown']
```

## VolumeType [#volumetype]

```python
VolumeType = Literal['disk', 'bucket', 'unknown']
```