Organizations and workspaces

New to the SDK? Getting started shows how to connect and use it.

Organizations

Organizations

The organizations the caller belongs to.

Organizations.get()

get(*, id: str) -> Organization

Return one organization by id.

Arguments

Name	Type	Description
id	str	The organization uuid.

Returns: Organization — The organization; awaitable in async mode.

Raises

Exception	When
BadRequest	The request was rejected as invalid; message, code and fields say why.
NotAuthorized	The caller lacks the access this call needs; message says why.
NotFound	No such organization.

Organizations.count()

count() -> int

Return how many organizations the caller belongs to.

Returns: int — The organization count; awaitable in async mode. Saturates at 10,001.

Organizations.list()

list(
    *,
    limit: int | None = None,
    offset: int = 0,
) -> Iterable[Organization] | AsyncIterable[Organization]

Yield the organizations the caller belongs to, paging lazily.

Needs no scope, so this is the entry point when the caller knows no ids yet.

Arguments

Name	Type	Description
limit	int | None	Return at most this many. None walks to the end, or to row 10,100, past which the platform does not page.
offset	int	Skip this many, server-side.

Returns: Iterable[Organization] | AsyncIterable[Organization] — An iterable of organizations; async-iterable in async mode.

Raises

Exception	When
ValueError	A negative limit or offset.

Organization

An organization: what workspaces, members and billing hang off.

Collections

Name	Type	Example	Description
organization.workspaces	Workspaces	organization.workspaces.list()	The workspaces in this organization.

Attributes

Name	Type	Description
id	str	Unique ID (a UUID).
name	str	The name of the organization.
description	str | None	Free-text description of the organization; None when none is set.
dataplane_id	str | None	Data plane of the organization's workspaces; None until a region is set.
created_at	datetime	When it was created.

Organization.set_dataplane()

set_dataplane(*, dataplane_id: str) -> Organization

Choose the data plane this organization's workspaces live on.

Must be set before the organization can hold any workspace, and it fixes where that data resides. One-time and irreversible.

Arguments

Name	Type	Description
dataplane_id	str	The data plane to assign.

Returns: Organization — A fresh snapshot; awaitable in async mode.

Raises

Exception	When
BadRequest	The request was rejected as invalid; message, code and fields say why.
Conflict	The current state does not allow the call, e.g. the workspace is archived; code and message say why.
NotAuthorized	The caller lacks the access this call needs; message says why.
NotFound	The organization does not exist.

Organization.me()

me() -> OrganizationCaller

Who the caller is here, what they may do, and where they belong.

One call, and it answers for an API key as well as a user token.

Returns: OrganizationCaller — The caller's identity, role, and workspace memberships in this organization; awaitable in async mode.

Raises

Exception	When
NotAuthorized	The caller lacks the access this call needs; message says why.
NotFound	The organization no longer exists.

Membership

A workspace the caller belongs to, and their role in it.

Attributes

Name	Type	Description
workspace	Workspace	The workspace, bound and ready to navigate from.
role	str	The role of the user in the workspace.

OrganizationCaller

Who the token belongs to, and what they may do in one organization.

Attributes

Name	Type	Description
email	str	The email of the current user.
user_id	str	The ID of the current user.
organization_membership_id	str	The ID of the organization member for this organization.
role	str	The role of the user in this organization.
workspace_memberships	tuple[Membership, ...]	The organization's workspaces the caller belongs to.

Workspaces

Workspaces

Workspace lookup, scoped by the context it is reached through.

Workspaces.create()

create(
    *,
    name: str,
    description: str | None = None,
    organization_id: str | None = None,
) -> Workspace

Create a workspace in an organization.

Arguments

Name	Type	Description
name	str	Name for the new workspace. Names need not be unique.
description	str | None	Free-text description, or None for none.
organization_id	str | None	Overrides the organization in scope. Required when the context carries none.

Returns: Workspace — The new workspace, scoped so its jobs are reachable; awaitable in async mode.

Raises

Exception	When
BadRequest	The request was rejected as invalid; message, code and fields say why.
Conflict	The current state does not allow the call, e.g. the workspace is archived; code and message say why.
NotAuthorized	The caller lacks the access this call needs; message says why.
NotFound	No such organization.
ScopeMissing	No organization in scope and none passed.

Workspaces.get()

get(*, id: str) -> Workspace

Return one workspace by id.

Arguments

Name	Type	Description
id	str	The workspace uuid.

Returns: Workspace — The workspace; awaitable in async mode.

Raises

Exception	When
BadRequest	The request was rejected as invalid; message, code and fields say why.
NotAuthorized	The caller lacks the access this call needs; message says why.
NotFound	No such workspace.

Workspaces.count()

count(*, organization_id: str | None = None) -> int

Count the workspaces of one organization, without fetching them.

Counts the live (unarchived) workspaces of the organization that the caller can see.

Arguments

Name	Type	Description
organization_id	str | None	Overrides the organization in scope. Required when the context carries none.

Returns: int — The workspace count; awaitable in async mode. Saturates at 10,001.

Raises

Exception	When
BadRequest	The request was rejected as invalid; message, code and fields say why.
NotAuthorized	The caller lacks the access this call needs; message says why.
NotFound	No such organization.
ScopeMissing	No organization in scope and none passed.

Workspaces.list()

list(
    *,
    organization_id: str | None = None,
    limit: int | None = None,
    offset: int = 0,
) -> Iterable[Workspace] | AsyncIterable[Workspace]

Yield the workspaces of one organization, paging lazily.

Yields the live (unarchived) workspaces of the organization that the caller can see. Errors from the platform are raised when iteration begins.

Arguments

Name	Type	Description
organization_id	str | None	Overrides the organization in scope. Required when the context carries none.
limit	int | None	Return at most this many workspaces. None walks to the end, or to row 10,100, past which the platform does not page.
offset	int	Skip this many workspaces, server-side.

Returns: Iterable[Workspace] | AsyncIterable[Workspace] — An iterable of workspaces; async-iterable in async mode.

Raises

Exception	When
BadRequest	The request was rejected as invalid; message, code and fields say why.
NotAuthorized	The caller lacks the access this call needs; message says why.
NotFound	No such organization.
ScopeMissing	No organization in scope and none passed.
ValueError	A negative limit or offset.

Workspace

A workspace: the unit a job is deployed into.

Collections

Name	Type	Example	Description
workspace.job_runs	JobRuns	workspace.job_runs.list()	The job runs of this workspace, across all its jobs.
workspace.deployments	Deployments	workspace.deployments.list()	The versions of code this workspace has been given.
workspace.configurations	Configurations	workspace.configurations.list()	The versions of configuration this workspace has been given.
workspace.telemetry	Telemetry	workspace.telemetry.status()	What the platform observed of the pipelines this workspace ran.
workspace.variables	Variables	workspace.variables.list()	The variables this workspace's job runs read.
workspace.jobs	Jobs	workspace.jobs.list()	The jobs deployed in this workspace.

Attributes

Name	Type	Description
id	str	Unique ID (a UUID).
name	str	The name of the workspace.
description	str | None	Free-text description of the workspace; None when none is set.
organization_id	str	The ID of the parent organization.
dataplane_id	str	Identifier of the data plane that holds this workspace's user data. Matches the subdomain of the plane's public entrypoint.
is_playground	bool	Whether this is the user's auto-created personal playground workspace. A playground has a single member and cannot be updated, archived, shared, or given API keys.
predefined_profiles	Mapping[str, str]	Profile names the platform offers for this workspace, keyed by access level. Empty when it declares none.
created_at	datetime	When it was created.
archived_at	datetime | None	When the workspace was archived; None when live. An archived workspace rejects all changes except unarchiving, though owners can still manage its workspace variables.
dashboard_url	str	Where this workspace's dashboard lives in the web UI.

Workspace.update()

update(*, name: str | Keep = KEEP, description: str | None | Keep = KEEP) -> Workspace

Change the workspace's name, its description, or both.

Arguments

Name	Type	Description
name	str | Keep	New name. Omit to leave it unchanged.
description	str | None | Keep	New description. Pass None to clear it, omit to leave it unchanged.

Returns: Workspace — A fresh snapshot; awaitable in async mode.

Raises

Exception	When
BadRequest	The request was rejected as invalid; message, code and fields say why.
Conflict	The current state does not allow the call, e.g. the workspace is archived; code and message say why.
NotAuthorized	The caller lacks the access this call needs; message says why.
NotFound	The workspace no longer exists.

Workspace.archive()

archive() -> Workspace

Freeze the workspace: its schedules stop and it refuses changes.

Returns: Workspace — A fresh snapshot with archived_at set; awaitable in async mode.

Raises

Exception	When
BadRequest	The request was rejected as invalid; message, code and fields say why.
Conflict	The current state does not allow the call, e.g. the workspace is archived; code and message say why.
NotAuthorized	The caller lacks the access this call needs; message says why.
NotFound	The workspace no longer exists.

Workspace.unarchive()

unarchive() -> Workspace

Reopen an archived workspace and restart its schedules.

Returns: Workspace — A fresh snapshot with archived_at cleared; awaitable in async mode.

Raises

Exception	When
Conflict	The current state does not allow the call, e.g. the workspace is archived; code and message say why.
NotAuthorized	The caller lacks the access this call needs; message says why.
NotFound	The workspace no longer exists.

Workspace.members()

members(
    *,
    limit: int | None = None,
    offset: int = 0,
) -> Iterable[WorkspaceMember] | AsyncIterable[WorkspaceMember]

Who has access to this workspace, and in what role.

Arguments

Name	Type	Description
limit	int | None	Return at most this many. None walks to the end, or to row 10,100, past which the platform does not page.
offset	int	Skip this many, server-side.

Returns: Iterable[WorkspaceMember] | AsyncIterable[WorkspaceMember] — An iterable of members; async-iterable in async mode.

Raises

Exception	When
NotAuthorized	The caller lacks the access this call needs; message says why.
ValueError	A negative limit or offset.

Workspace.me()

me() -> WorkspaceCaller

Who the caller is here, and what they may do.

One call, and it answers for an API key as well as a user token. Also records this workspace as the caller's most recent one, so Runtime.me() then reports its organization as latest_organization.

Returns: WorkspaceCaller — The caller's identity and roles; awaitable in async mode.

Raises

Exception	When
NotAuthorized	The caller lacks the access this call needs; message says why.
NotFound	The workspace no longer exists.

WorkspaceCaller

Who the token belongs to, and what they may do in one workspace.

Attributes

Name	Type	Description
email	str	The email of the current user.
user_id	str	The ID of the current user.
organization_membership_id	str	The ID of the organization member in the parent organization.
organization_id	str	Unique ID (a UUID).
organization_role	str	The role of the user in the parent organization.
workspace_role	str	The role of the user in this workspace.

WorkspaceMember

One member of a workspace: a person or a service account (workspace API key).

Attributes

Name	Type	Description
email	str	The email of the user.
user_id	str	The ID of the user.
role	str	The role of the user in the workspace.
name	str | None	Display name; None when the user has no name set.

Caller

Caller

The person the token belongs to.

Returned for a user token or a user API key; a service-account API key gets dlthub_sdk.NotAuthorized instead (see dlthub_sdk.Runtime.me()). Organization.me() and Workspace.me() answer for any caller.

Attributes

Name	Type	Description
email	str	The email of the current user.
user_id	str	The ID of the current user.
organization_membership_id	str	Your membership id in latest_organization.
name	str | None	The user's display name (full name); None if the identity provider supplied none.
primary_organization	Organization	The organization where new workspaces are created by default.
latest_organization	Organization	The organization you used most recently.
organization_memberships	tuple[OrganizationMembership, ...]	Every organization they belong to.

OrganizationMembership

An organization the caller belongs to, and their role in it.

Attributes

Name	Type	Description
organization	Organization	The organization, bound and ready to navigate from.
role	str	The role of the user in the organization.
is_active	bool	Whether the membership is active.

Data planes

Dataplanes

The data planes this caller may choose from.

They arrive in one answer, so there is nothing to page and no count to ask for.

Dataplanes.list()

list() -> tuple[Dataplane, ...]

Return every data plane available to this caller.

Needs no scope, like Organizations.list().

Returns: tuple[Dataplane, ...] — All of them, in the platform's order; awaitable in async mode.

Dataplane

A data plane an organization can put its workspaces on.

Attributes

Name	Type	Description
id	str	Data plane id, e.g. eu1; also the subdomain of its URL.
name	str	Human-readable data plane name.
region	str	Cloud region the data plane runs in, e.g. europe-west4.
description	str | None	Optional note about the data plane; None when there is none.