> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Functions

> Query available runners and profiles.

## list\_runners

Source: [src/cwsandbox/\_discovery.py:405](https://github.com/coreweave/cwsandbox-client/blob/v0.22.0/src/cwsandbox/_discovery.py#L405)

```python theme={"system"}
list_runners(*, runner_group_id: str | None = None, profile_name: str | None = None, gpu_type: str | None = None, architecture: str | None = None, include_resources: bool = False, min_available_cpu_millicores: int | None = None, min_available_memory_bytes: int | None = None, min_available_gpu_count: int | None = None, service_exposure_mode: str | None = None, egress_mode: str | None = None) -> list[Runner]
```

List available runners, optionally filtered.

Creates a gRPC channel, issues the RPC(s), and closes the channel before
returning.  Automatically paginates when the server returns a
`next_page_token`.
**Parameters**

* `runner_group_id` (`str | None`): Restrict results to this runner group.
* `profile_name` (`str | None`): Only return runners that have this profile.
* `gpu_type` (`str | None`): Only return runners that support this GPU type.
* `architecture` (`str | None`): Only return runners that support this CPU architecture.
* `include_resources` (`bool`): If `True`, include live resource availability on each runner. Defaults to `False` (basic view).
* `min_available_cpu_millicores` (`int | None`): Only return runners with at least this many unreserved CPU millicores. Automatically enables `include_resources`. Filtered client-side.
* `min_available_memory_bytes` (`int | None`): Only return runners with at least this many unreserved memory bytes. Automatically enables `include_resources`. Filtered client-side.
* `min_available_gpu_count` (`int | None`): Only return runners with at least this many unreserved GPUs. Automatically enables `include_resources`. Filtered client-side.
* `service_exposure_mode` (`str | None`): Only return runners whose profiles support this service exposure mode. Requires an additional profile fetch. Filtered client-side.
* `egress_mode` (`str | None`): Only return runners whose profiles support this egress mode. Requires an additional profile fetch. Filtered client-side.

**Note:** The `service_exposure_mode` and `egress_mode` filters check across **all** profiles on each runner, not only the profile specified by `profile_name`. A runner will match if *any* of its profiles provides the requested mode, even if the profile selected by `profile_name` does not.

**Returns**

* `list[Runner]`: List of `Runner` objects matching the filters.

**Raises**

* `CWSandboxAuthenticationError`: If credentials are invalid.
* `CWSandboxError`: On network or service errors.

***

## get\_runner

Source: [src/cwsandbox/\_discovery.py:530](https://github.com/coreweave/cwsandbox-client/blob/v0.22.0/src/cwsandbox/_discovery.py#L530)

```python theme={"system"}
get_runner(runner_id: str) -> Runner
```

Get a single runner by ID.

Always returns full details including resource availability.
**Parameters**

* `runner_id` (`str`): Unique identifier of the runner.

**Returns**

* `Runner`: `Runner` with full details.

**Raises**

* `ValueError`: If *runner\_id* is empty.
* `RunnerNotFoundError`: If no runner exists with the given ID.
* `CWSandboxAuthenticationError`: If credentials are invalid.
* `CWSandboxError`: On network or service errors.

***

## list\_profiles

Source: [src/cwsandbox/\_discovery.py:609](https://github.com/coreweave/cwsandbox-client/blob/v0.22.0/src/cwsandbox/_discovery.py#L609)

```python theme={"system"}
list_profiles(*, gpu_type: str | None = None, architecture: str | None = None, runner_id: str | None = None, service_exposure_mode: str | None = None, egress_mode: str | None = None) -> list[Profile]
```

List available profiles, optionally filtered.

Creates a gRPC channel, issues the RPC(s), and closes the channel before
returning.  Automatically paginates when the server returns a
`next_page_token`.
**Parameters**

* `gpu_type` (`str | None`): Only return profiles that support this GPU type.
* `architecture` (`str | None`): Only return profiles that support this CPU architecture.
* `runner_id` (`str | None`): Only return profiles belonging to this runner.
* `service_exposure_mode` (`str | None`): Only return profiles that support this service exposure mode. Filtered client-side after fetching results from the backend.
* `egress_mode` (`str | None`): Only return profiles that support this egress mode. Filtered client-side after fetching results from the backend.

**Returns**

* `list[Profile]`: List of `Profile` objects matching the filters.

**Raises**

* `CWSandboxAuthenticationError`: If credentials are invalid.
* `CWSandboxError`: On network or service errors.

***

## get\_profile

Source: [src/cwsandbox/\_discovery.py:698](https://github.com/coreweave/cwsandbox-client/blob/v0.22.0/src/cwsandbox/_discovery.py#L698)

```python theme={"system"}
get_profile(profile_name: str, *, runner_id: str | None = None) -> Profile
```

Get a single profile by name.
**Parameters**

* `profile_name` (`str`): Name of the profile to retrieve.
* `runner_id` (`str | None`): Optionally scope the lookup to a specific runner.

**Returns**

* `Profile`: `Profile` matching the given name.

**Raises**

* `ValueError`: If *profile\_name* is empty.
* `ProfileNotFoundError`: If no matching profile is found.
* `CWSandboxAuthenticationError`: If credentials are invalid.
* `CWSandboxError`: On network or service errors.

***

## format\_bytes

Source: [src/cwsandbox/\_discovery.py:43](https://github.com/coreweave/cwsandbox-client/blob/v0.22.0/src/cwsandbox/_discovery.py#L43)

```python theme={"system"}
format_bytes(value: int) -> str
```

Format bytes as a human-readable string using binary units.
**Parameters**

* `value` (`int`): Number of bytes.

**Returns**

* `str`: Human-readable string with appropriate unit.

**Examples**

```text theme={"system"}
>>> format_bytes(17179869184)
'16.0 GiB'
>>> format_bytes(0)
'0 B'
```

***

## format\_cpu

Source: [src/cwsandbox/\_discovery.py:71](https://github.com/coreweave/cwsandbox-client/blob/v0.22.0/src/cwsandbox/_discovery.py#L71)

```python theme={"system"}
format_cpu(millicores: int) -> str
```

Format CPU millicores as a human-readable string.
**Parameters**

* `millicores` (`int`): CPU capacity in millicores.

**Returns**

* `str`: Human-readable string in cores.

**Examples**

```text theme={"system"}
>>> format_cpu(4000)
'4.0 vCPU'
>>> format_cpu(500)
'0.5 vCPU'
```

***