Python SDK reference

This page documents the public API of the h2o-workflows Python SDK. This SDK provides two login functions and a Clients bundle that gives you access to typed clients for each Workflows resource.

login()

def login(
    environment: str | None = None,
    token_provider: TokenProvider | None = None,
    platform_token: str | None = None,
    config_path: str | None = None,
    verify_ssl: bool = True,
    ssl_ca_cert: str | None = None,
) -> Clients

Initializes Workflows clients for H2O AI Cloud.

Note

All arguments are optional. Configuration-less login depends on having the H2O CLI configured.

Parameters

Parameter	Type	Default	Description
environment	str | None	None	The H2O Cloud environment URL (e.g., https://cloud.h2o.ai). If omitted, reads from H2O CLI config.
token_provider	TokenProvider | None	None	Token provider. Takes priority over platform_token.
platform_token	str | None	None	H2O Platform Token. If neither token_provider nor platform_token is provided, reads from H2O CLI config.
config_path	str | None	None	Path to H2O AI Cloud config file. Defaults to ~/.h2oai/h2o-cli-config.toml.
verify_ssl	bool	True	Set to False to disable SSL certificate verification.
ssl_ca_cert	str | None	None	Path to a CA cert bundle.

Returns: Clients

Raises:

• FileNotFoundError — When the H2O CLI configuration file is needed but cannot be found.
• LookupError — When the service endpoint cannot be discovered.
• ConnectionError — When a communication with server failed.

Example

import h2o_workflows

clients = h2o_workflows.login()

login_custom()

def login_custom(
    endpoint: str,
    refresh_token: str,
    issuer_url: str,
    client_id: str,
    client_secret: str | None = None,
    verify_ssl: bool = True,
    ssl_ca_cert: str | None = None,
) -> Clients

Initializes Workflows clients with explicit connection parameters. Use this when you cannot rely on H2O CLI configuration or the Discovery Service.

Parameters

Parameter	Type	Default	Description
endpoint	str	required	The Workflows service endpoint URL (e.g., https://workflows.cloud.h2o.ai).
refresh_token	str	required	The OIDC refresh token.
issuer_url	str	required	The OIDC issuer URL.
client_id	str	required	The OIDC Client ID that issued the refresh_token.
client_secret	str | None	None	Optional OIDC Client Secret that issued the refresh_token.
verify_ssl	bool	True	Set to False to disable SSL certificate verification.
ssl_ca_cert	str | None	None	Path to a CA cert bundle.

Returns: Clients

Example

import h2o_workflows

clients = h2o_workflows.login_custom(
    endpoint="https://workflows.cloud.h2o.ai",
    refresh_token="your-refresh-token",
    issuer_url="https://auth.cloud.h2o.ai/",
    client_id="your-client-id",
)

Clients

The Clients class bundles typed clients returned by login() and login_custom().

Attribute	Type
.workflow	WorkflowClient
.workflow_revision	WorkflowRevisionClient
.run	RunClient
.run_attempt	RunAttemptClient
.job	JobClient
.step	StepClient
.runner	RunnerClient

WorkflowClient

WorkflowClient manages Workflows. Access it via clients.workflow.

list_workflows(parent, page_size, page_token)

Lists Workflows in a workspace.

Parameters

Parameter	Type	Default	Description
parent	str	required	The parent workspace. Format: workspaces/{workspace}.
page_size	int	0	Maximum number of workflows to return. 0 uses the server default.
page_token	str	""	Token for retrieving the next page of results.

Returns: WorkflowsPage

get_workflow(name)

Gets a Workflow.

Parameters

Parameter	Type	Description
name	str	The resource name. Format: workspaces/{workspace}/workflows/{workflow}.

Returns: Workflow

create_workflow(parent, workflow)

Creates a Workflow.

Parameters

Parameter	Type	Description
parent	str	The parent workspace. Format: workspaces/{workspace}.
workflow	Workflow	The workflow to create.

Returns: Workflow

update_workflow(workflow, update_mask)

Updates a Workflow.

Parameters

Parameter	Type	Default	Description
workflow	Workflow	required	The workflow to update. The name field identifies the resource.
update_mask	str	"*"	The field mask to use for the update. Allowed field paths: source_contents. Default "*" updates all updatable fields.

Returns: Workflow

delete_workflow(name)

Deletes a Workflow.

Parameters

Parameter	Type	Description
name	str	The resource name. Format: workspaces/{workspace}/workflows/{workflow}.

Returns: None

activate_workflow(name)

Activates a Workflow, making it eligible for scheduling and manual triggering.

Parameters

Parameter	Type	Description
name	str	The resource name. Format: workspaces/{workspace}/workflows/{workflow}.

Returns: Workflow

deactivate_workflow(name)

Deactivates a Workflow, preventing further scheduled or manual runs.

Parameters

Parameter	Type	Description
name	str	The resource name. Format: workspaces/{workspace}/workflows/{workflow}.

Returns: Workflow

validate_workflow(parent, source_contents)

Validates workflow source contents against the schema and semantic rules.

Parameters

Parameter	Type	Description
parent	str	The parent workspace. Format: workspaces/{workspace}.
source_contents	str	The YAML source contents to validate.

Returns: ValidateWorkflowResponse

RunClient

RunClient manages Runs. Access it via clients.run.

list_runs(parent, page_size, page_token)

Lists Runs for a workflow revision.

Parameters

Parameter	Type	Default	Description
parent	str	required	The parent workflow revision. Format: workspaces/{workspace}/workflows/{workflow}/revisions/{revision}.
page_size	int	0	Maximum number of runs to return. 0 uses the server default.
page_token	str	""	Token for retrieving the next page of results.

Returns: RunsPage

get_run(name)

Gets a Run.

Parameters

Parameter	Type	Description
name	str	The resource name.

Returns: Run

cancel_run(name)

Cancels a Run.

Parameters

Parameter	Type	Description
name	str	The resource name.

Returns: Run

delete_run(name)

Deletes a Run.

Parameters

Parameter	Type	Description
name	str	The resource name.

Returns: None

retry_run(name, retry_mode)

Retries a failed Run.

Parameters

Parameter	Type	Default	Description
name	str	required	The resource name.
retry_mode	str | None	None	The retry mode.

Returns: Run

---

Feedback

• Submit and view feedback for this page
• Send feedback about H2O Workflows to cloud-feedback@h2o.ai