API Reference¶

Reference documentation for the Pipelines client and related types.

All classes below are available via from kubeflow.pipelines import ....

Pipelines Client¶

class kubeflow.pipelines.PipelinesClient(backend_config: KubernetesBackendConfig | None = None) → None[source]¶

Bases: object

Simplified, name-first client for Kubeflow Pipelines.

Provides the core author → compile → upload → run → monitor workflow from a single import. Designed to be re-exported by the Kubeflow SDK at kubeflow.pipelines.PipelinesClient.

Parameters:: backend_config (KubernetesBackendConfig | None) – Connection parameters for the KFP API server. When None, uses KubernetesBackendConfig() (zero-arg construction with auto-discovery).

upload_pipeline(pipeline: Callable | str, *, name: str | None = None, version: str | None = None, description: str | None = None) → PipelineVersion[source]¶

Upload a pipeline (or new version) to the server.

Handles callable functions, file paths, new pipelines, and new versions through a single unified method.

Note

When creating a new pipeline with an explicit version name, the server auto-generates the first version name during upload. A best-effort rename is attempted afterward; if the rename fails (e.g. due to permissions), a warning is logged and the returned version retains the server-generated name.

Parameters:

pipeline (Callable | str) – A @dsl.pipeline-decorated function or a path to a compiled pipeline YAML file.
name (str | None) – Display name for the pipeline. If omitted, auto-generated from the function’s @dsl.pipeline(name=...) value or the filename without extension.
version (str | None) – Version label. If omitted, auto-generated. Calling upload_pipeline again with the same name and no explicit version creates a new version each time.
description (str | None) – Pipeline description.

Returns:

A PipelineVersion object representing the uploaded version.

get_pipeline(name: str) → Pipeline[source]¶

Get a pipeline by name.

Parameters:: name (str) – Pipeline display name.
Returns:: A Pipeline object.
Raises:: ValueError – If no pipeline matches or multiple pipelines match.

get_pipeline_version(name: str, version: str) → PipelineVersion[source]¶

Get a specific pipeline version by pipeline name and version name.

Parameters:

name (str) – Pipeline display name.
version (str) – Version display name.

Returns:

A PipelineVersion object.

Raises:

ValueError – If the pipeline or version is not found.

list_pipelines(*, page_token: str = '', page_size: int = 10) → ListPipelinesResponse[source]¶

List pipelines available on the server.

Parameters:

page_token (str) – Token for obtaining the next page.
page_size (int) – Number of results per page.

Returns:

A ListPipelinesResponse with .pipelines and .next_page_token.

list_pipeline_versions(name: str, *, page_token: str = '', page_size: int = 10) → ListPipelineVersionsResponse[source]¶

List versions of a pipeline by name.

Parameters:

name (str) – Pipeline display name.
page_token (str) – Token for obtaining the next page.
page_size (int) – Number of results per page.

Returns:

A ListPipelineVersionsResponse with .pipeline_versions and .next_page_token.

delete_pipeline(name: str, *, version: str | None = None, force: bool = False) → None[source]¶

Delete a pipeline or a specific pipeline version.

Parameters:

name (str) – Pipeline display name.
version (str | None) – If provided, delete only this version. If None, delete the entire pipeline and all versions.
force (bool) – When deleting an entire pipeline, required if the pipeline has more than one version. Ignored when version is set.

Raises:

ValueError – If the pipeline has multiple versions and force=False.

Run a pipeline.

Supports multiple input types: - A pipeline name (str without file extension): resolves the

uploaded pipeline on the server.

A path to a compiled YAML file (str ending in .yaml/ .yml): compile-and-submit inline, no upload.
A @dsl.pipeline-decorated callable: compile-and-submit inline.
A Pipeline or PipelineVersion object (from get_pipeline/upload_pipeline).

Note

String inputs are classified as file paths when they end in .yaml or .yml. If you have an uploaded pipeline whose display name ends with such an extension, pass the Pipeline object from get_pipeline() instead.

Parameters:

pipeline (str | Callable | Pipeline | PipelineVersion) – Pipeline to run (see above).
params (dict[str, Any] | None) – Pipeline parameters as a dict.
name (str | None) – Run display name. Auto-generated if omitted.
experiment (str | None) – Experiment name. If None, the server’s default experiment is used. If provided and the experiment does not exist, raises ValueError.
version (str | None) – Pipeline version name (used when pipeline is a name string or a Pipeline object). Uses latest version if omitted.

Returns:

A Run object.

get_run(run_id: str) → Run[source]¶

Get a run by ID.

Parameters:: run_id (str) – The run identifier.
Returns:: A Run object.

list_runs(*, pipeline: str | None = None, experiment: str | None = None, status: str | None = None, page_token: str = '', page_size: int = 10) → ListRunsResponse[source]¶

List runs, optionally filtered by pipeline, experiment, or status.

Note

The pipeline filter is applied client-side because the KFP v2beta1 API does not support server-side filtering by pipeline ID. When used, the returned page may contain fewer items than page_size — including zero items with a non-empty next_page_token if all runs on that server page belong to other pipelines. Callers should continue paginating until next_page_token is empty.

Parameters:

pipeline (str | None) – Filter by pipeline display name (client-side).
experiment (str | None) – Filter by experiment display name.
status (str | None) – Filter by run state (e.g. "succeeded").
page_token (str) – Token for obtaining the next page.
page_size (int) – Number of results per page.

Returns:

A ListRunsResponse with .runs and .next_page_token.

wait_for_run_status(run: str | Run, *, status: set[str] | None = None, timeout: int | None = 600, polling_interval: int = 5, callbacks: list[Callable[[Run], None]] | None = None) → Run[source]¶

Wait for a run to reach a target state.

Parameters:

run (str | Run) – A Run object or a run ID string.
status (set[str] | None) – Set of states to wait for. Defaults to {constants.RUN_COMPLETE} ("succeeded"). The wait always exits immediately on any terminal state regardless of this parameter.
timeout (int | None) – Maximum seconds to wait. Defaults to 600 (10 minutes). Pass None to wait indefinitely.
polling_interval (int) – Seconds between status checks.
callbacks (list[Callable[[Run], None]] | None) – Called with the final Run object when the wait ends (on any stop condition).

Returns:

The Run object at the time the wait concluded.

Raises:

TimeoutError – If timeout expires before reaching a stop condition.

create_experiment(name: str, *, description: str | None = None) → Experiment[source]¶

Create a new experiment.

If an experiment with the given name already exists, returns it.

Parameters:

name (str) – Experiment display name.
description (str | None) – Experiment description.

Returns:

An Experiment object.

get_experiment(name: str) → Experiment[source]¶

Get an experiment by name.

Parameters:: name (str) – Experiment display name.
Returns:: An Experiment object.
Raises:: ValueError – If no experiment with that name is found.

list_experiments(*, page_token: str = '', page_size: int = 10) → ListExperimentsResponse[source]¶

List experiments.

Parameters:

page_token (str) – Token for obtaining the next page.
page_size (int) – Number of results per page.

Returns:

A ListExperimentsResponse with .experiments and .next_page_token.

delete_experiment(name: str) → None[source]¶

Delete an experiment by name.

Parameters:: name (str) – Experiment display name.
Raises:: ValueError – If no experiment with that name is found.

property kfp_client: Client¶

Access the underlying kfp.Client for advanced operations.

Lazily constructed on first access, sharing connection parameters from KubernetesBackendConfig.

Backend Configuration¶

Bases: object

Connection configuration for the KFP API server.

Parameters:

base_url (str | None) – KFP API server URL including scheme and port (e.g. https://ml-pipeline.example.com:8080). If omitted, auto-discovered following kfp.Client conventions (in-cluster DNS or kubeconfig proxy).
user_token (str | None) – Bearer token for authentication.
is_secure (bool | None) – Whether to verify TLS certificates (controls verify_ssl on the underlying HTTP client). Does not control whether the connection uses TLS — that is determined by the URL scheme. Inferred from scheme if omitted (True for https, False for http).
custom_ca (str | None) – Path to PEM-encoded root certificates.
namespace (str | None) – Kubernetes namespace. If omitted, auto-detected.

base_url: str | None = None¶

user_token: str | None = None¶

is_secure: bool | None = None¶

custom_ca: str | None = None¶

namespace: str | None = None¶

Types¶

Available via from kubeflow.pipelines import Pipeline, PipelineVersion, Run, Experiment.

These are type aliases for the auto-generated kfp_server_api model classes:

Pipeline — a pipeline registered on the server
PipelineVersion — an immutable snapshot of a pipeline
Run — a single execution of a pipeline
Experiment — a logical grouping of runs
ListPipelinesResponse — paginated list of pipelines
ListPipelineVersionsResponse — paginated list of pipeline versions
ListRunsResponse — paginated list of runs
ListExperimentsResponse — paginated list of experiments

Constants¶

Available via from kubeflow.pipelines import constants.

kubeflow.pipelines.constants.RUN_SUCCEEDED¶: 'succeeded'

kubeflow.pipelines.constants.RUN_FAILED¶: 'failed'

kubeflow.pipelines.constants.RUN_SKIPPED¶: 'skipped'

kubeflow.pipelines.constants.RUN_CANCELED¶: 'canceled'

kubeflow.pipelines.constants.RUN_CANCELING¶: 'canceling'

kubeflow.pipelines.constants.RUN_RUNNING¶: 'running'

kubeflow.pipelines.constants.RUN_PENDING¶: 'pending'

kubeflow.pipelines.constants.RUN_PAUSED¶: 'paused'

kubeflow.pipelines.constants.RUN_COMPLETE¶: Alias for RUN_SUCCEEDED.

kubeflow.pipelines.constants.TERMINAL_STATES¶: frozenset({'succeeded', 'failed', 'skipped', 'canceled'})