---
title: Client
description: Client in the dltHub Runtime Python SDK (dlthub_sdk)
keywords: [dlthub, runtime, python sdk, dlthub_sdk, api]
---
# Client

<!-- generated from dlthub-client 0.28.8a3, do not edit -->

New to the SDK? [Getting started](getting-started.md) shows how to connect and use it.

## Connecting

### `connect()` {#connect}

```python
connect(
    *,
    token: str | None = None,
    credentials: Credentials | None = None,
    base_url: str = 'https://api.dlthub.com',
    organization_id: str | None = None,
    verify_ssl: bool = True,
    headers: Mapping[str, str] | None = None,
) -> Runtime[Sync]
```

Connect to the platform for blocking use.

**Arguments**

| Name | Type | Description |
| --- | --- | --- |
| `token` | <code>str &#124; None</code> | An API key (`dlt_u_`/`dlt_sa_` prefixed) or a user JWT, when the credential does not change. A JWT is not renewed, so a long-lived client should hold an API key or pass `credentials`. |
| `credentials` | <code><a href="#credentials">Credentials</a> &#124; None</code> | Where to read the credential before each request, for one that rotates. Renewed once if the platform rejects it. Exactly one of this and `token` is required. |
| `base_url` | <code>str</code> | Platform base URL. Override for local or staging. |
| `organization_id` | <code>str &#124; None</code> | Default organization, so `workspaces.list()` needs no argument. |
| `verify_ssl` | <code>bool</code> | Verify the platform's TLS certificate. Applies on both planes. |
| `headers` | <code>Mapping[str, str] &#124; None</code> | Sent with every request, on both planes. |

**Returns:** <code><a href="#runtime">Runtime</a>[<a href="#sync">Sync</a>]</code> — A blocking [`Runtime`](#runtime).

**Raises**

| Exception | When |
| --- | --- |
| `ValueError` | Both `token` and `credentials`, or neither. |

### `connect_async()` {#connect_async}

```python
connect_async(
    *,
    token: str | None = None,
    credentials: AsyncCredentials | None = None,
    base_url: str = 'https://api.dlthub.com',
    organization_id: str | None = None,
    verify_ssl: bool = True,
    headers: Mapping[str, str] | None = None,
) -> Runtime[Async]
```

Connect to the platform for awaited use.

**Arguments**

| Name | Type | Description |
| --- | --- | --- |
| `token` | <code>str &#124; None</code> | As for [`connect()`](#connect). |
| `credentials` | <code><a href="#asynccredentials">AsyncCredentials</a> &#124; None</code> | As for [`connect()`](#connect), awaited. |
| `base_url` | <code>str</code> | Platform base URL. Override for local or staging. |
| `organization_id` | <code>str &#124; None</code> | Default organization, so `workspaces.list()` needs no argument. |
| `verify_ssl` | <code>bool</code> | As for [`connect()`](#connect). |
| `headers` | <code>Mapping[str, str] &#124; None</code> | As for [`connect()`](#connect). |

**Returns:** <code><a href="#runtime">Runtime</a>[<a href="#async">Async</a>]</code> — An awaiting [`Runtime`](#runtime).

**Raises**

| Exception | When |
| --- | --- |
| `ValueError` | As for [`connect()`](#connect). |

## Runtime

### `Runtime` {#runtime}

Entry point to the platform.

Build one with `dlthub_sdk.connect()` or
`dlthub_sdk.connect_async()`; `M` records which, so every object
reached from it stays in the same mode.

Usable as a context manager (`with dlthub_sdk.connect(...) as runtime:`), which
closes it on the way out.

A runtime from `connect_async` needs `async with`; plain `with` raises
`TypeError`.

**[Collections](getting-started.md#collections-and-attributes)**

| Name | Type | Example | Description |
| --- | --- | --- | --- |
| `runtime.organizations` | <code><a href="organizations-and-workspaces#organizations">Organizations</a></code> | `runtime.organizations.list()` | Organization lookup. |
| `runtime.dataplanes` | <code><a href="organizations-and-workspaces#dataplanes">Dataplanes</a></code> | `runtime.dataplanes.list()` | The data planes a workspace can be placed on. |
| `runtime.workspaces` | <code><a href="organizations-and-workspaces#workspaces">Workspaces</a></code> | `runtime.workspaces.list()` | Workspace lookup. |

#### `Runtime.me()` {#runtime-me}

```python
me() -> Caller
```

Return the person this token belongs to.

Works with a user token or a user API key. A service-account API key or
a platform run's identity is refused; [`Organization.me()`](organizations-and-workspaces.md#organization-me) and
[`Workspace.me()`](organizations-and-workspaces.md#workspace-me) answer for those too.

Not side-effect free: it accepts the person's pending invitations, and
on their first call creates a personal organization and playground
workspace.

**Returns:** <code><a href="organizations-and-workspaces#caller">Caller</a></code> — The caller, with every organization they belong to; awaitable in async mode.

**Raises**

| Exception | When |
| --- | --- |
| [`NotAuthorized`](errors.md#notauthorized) | The caller lacks the access this call needs; `message` says why. |
| [`NotAuthenticated`](errors.md#notauthenticated) | The token is missing, malformed, or rejected. |

#### `Runtime.close()` {#runtime-close}

```python
close() -> Any
```

Release the connections held for this client.

Anything reached from it — a workspace, a job, a collection — shares
those connections, so close only when done with all of them. Calls
after close raise `RuntimeError`.

**Returns:** <code>Any</code> — `None`; awaitable in async mode.

## Credentials

### `AsyncCredentials` {#asynccredentials}

The awaited twin of [`Credentials`](#credentials), for `connect_async`.

#### `AsyncCredentials.token()` {#asynccredentials-token}

```python
token() -> str
```

Return the credential to send now.

**Returns:** <code>str</code> — The bearer token.

#### `AsyncCredentials.refreshed()` {#asynccredentials-refreshed}

```python
refreshed() -> str | None
```

Renew the credential after the platform rejected it.

**Returns:** <code>str &#124; None</code> — A token to retry with, or `None` to give up.

### `Credentials` {#credentials}

A control-plane credential the SDK reads before each request.

Implement this for a credential that changes over the client's life. The
SDK never stores what `token()` returns, so a rotation takes effect on
the next request.

#### `Credentials.token()` {#credentials-token}

```python
token() -> str
```

Return the credential to send now.

Called before every control-plane request, so an implementation that
renews proactively does it here.

**Returns:** <code>str</code> — The bearer token.

#### `Credentials.refreshed()` {#credentials-refreshed}

```python
refreshed() -> str | None
```

Renew the credential after the platform rejected it.

Called at most once per request, only for a 401. Returning `None`
makes the rejection final and the caller sees `NotAuthenticated`.

**Returns:** <code>str &#124; None</code> — A token to retry with, or `None` to give up.

## Conventions

Update methods leave a field as it is when you pass `KEEP`, the default of every optional update argument, clear it when you pass `None` and set it when you pass a value.

### `Async` {#async}

```python
Async = Literal['async']
```

Mode of a client from [`connect_async()`](#connect_async), as in `Runtime[Async]`.

Calls return awaitables and listings return async iterables.

### `KEEP` {#KEEP}

```python
KEEP = _Keep.KEEP
```

Leave this field as it is: the default of every optional update argument.

Pass `None` to clear a field instead.

### `Keep` {#keep}

```python
Keep = Literal[_Keep.KEEP]
```

The type of [`KEEP`](#KEEP), for annotating an update argument: `str | None | Keep`.

### `Sync` {#sync}

```python
Sync = Literal['sync']
```

Mode of a client from [`connect()`](#connect), as in `Runtime[Sync]`.

Calls return values and listings return iterables.