Python API

Submit, monitor, list, and retrieve results for pipeline jobs with the ionworks-api Python client.

The ionworks-api Python package exposes client.pipeline for running and managing pipelines. For installation and authentication, see the Python API client page.

Submitting a pipeline

import ionworks_schema as iws
from ionworks import Ionworks

# Reads IONWORKS_API_KEY and IONWORKS_PROJECT_ID from the environment.
client = Ionworks()

pipeline = iws.Pipeline(
    {
        "known": iws.direct_entries.DirectEntry(
            parameters={"Ambient temperature [K]": 298.15},
        ),
        "Q_pos": iws.calculations.ElectrodeCapacity(electrode="positive"),
    },
    name="Capacity pipeline",
)

submission = client.pipeline.create(pipeline)
print(f"Pipeline ID: {submission.id}")
print(f"Status: {submission.status}")

client.pipeline.create() accepts either an iws.Pipeline schema instance or the dict returned by .to_config(). Schema instances are validated locally before submission, so shape errors surface immediately.

Serializing a pipeline to JSON

Use .to_config() when you want to inspect, cache, or transport the pipeline payload as JSON — for example to review it before submission, commit it to version control, or hand it off to another process.

import json

config = pipeline.to_config()

# Inspect or save
with open("pipeline_config.json", "w") as f:
    json.dump(config, f, indent=2)

# Submit later, or from another process
submission = client.pipeline.create(config)

.to_config() is the only supported serializer. It emits the discriminators pipeline elements and objectives need (top-level elements are keyed on element_type, and nested schemas carry their own type), and emits each field under its wire name (for example, data_input → data).

Do not use Pydantic’s model_dump() to build API payloads. model_dump() drops these discriminators and emits Python attribute names instead of wire names, so it produces a dict the API may reject.

Overriding submission metadata

create() accepts optional project_id, name, description, and options kwargs that override any values carried on the schema:

submission = client.pipeline.create(
    pipeline,
    project_id="your-project-id",
    name="Custom run name",
    options={"live_progress_updates": True},
)

When project_id is omitted, the client falls back to the default configured on Ionworks(...) or the IONWORKS_PROJECT_ID environment variable.

Waiting for completion

submission = client.pipeline.wait_for_completion(
    submission.id,
    timeout=600,        # seconds (default: 600)
    poll_interval=2,    # seconds between polls (default: 2)
    verbose=True,       # print status updates (default: True)
)

Pass raise_on_failure=False to get the failed submission response back instead of raising when the pipeline errors out.

Retrieving results

result = client.pipeline.result(submission.id)

# Final parameter values produced by the pipeline
print(result.result)

# Per-element output keyed by the element name used in the Pipeline
print(result.element_results["Q_pos"])

result.element_results mirrors the keys you passed to iws.Pipeline(elements=...).

Element metadata

Some elements (notably Validation) write extra metadata that isn’t included in element_results. Fetch it with:

metadata = client.pipeline.get_element_metadata(submission.id, "validate")

Data-fit parameter trace

Data-fit elements log the optimizer’s per-iteration progress to the element’s job metadata. Pull it down with client.job.get_parameter_trace using the element’s job ID — see Inspecting the parameter trace for the full schema.

The element’s job_id lives in the pipeline’s elements list rather than in element_results, so fetch the list and pick out the data-fit element by name:

elements = client.get(f"/pipelines/{submission.id}/elements")
fit_job_id = next(e["job_id"] for e in elements if e["name"] == "fit")

trace = client.job.get_parameter_trace(fit_job_id)

Data-fit model-vs-data plot data

client.job.get_plot_data returns the model-vs-data traces for a data-fit job — the same overlay Studio renders on the fit’s results page. A data-fit re-runs a validation on its best-fit parameters and stores the overlay in its own metadata, so you can fetch it directly from the fit’s job ID without adding a separate Validation element or parsing the raw metadata blob.

plot = client.job.get_plot_data(
    fit_job_id,
    objective_name="1C",   # key used in the DataFit's objectives mapping
)

Use this when you want to reproduce the fit overlay in a notebook or report, or feed it into your own plotting pipeline.

Traces are decimated server-side to at most max_points points per series (default 2000, range 100–10000). For semantic zoom — refetching more detail as a user zooms in — pass x_min and x_max set to the current viewport:

zoomed = client.job.get_plot_data(
    fit_job_id,
    objective_name="1C",
    x_min=1200.0,
    x_max=1800.0,
    max_points=5000,
)

Parameter	Description
job_id	The data-fit job whose overlay to fetch.
objective_name	Key in the DataFit’s objectives mapping (for example, "1C" in the example above).
plot_index	Index into the objective’s list of plots when it defines several. Defaults to 0.
max_points	Maximum points returned per trace (100–10000). Defaults to 2000.
x_min, x_max	Inclusive x-range bounds. Omit for the full range.

Listing pipelines

# Defaults to the project on Ionworks(...) or IONWORKS_PROJECT_ID
pipelines = client.pipeline.list()

# Override the project for a single call
pipelines = client.pipeline.list(project_id="other-project-id")

# Limit the number of results
pipelines = client.pipeline.list(limit=10)

Getting a single submission

submission = client.pipeline.get(submission.id)
print(submission.status)  # "pending", "running", "completed", or "failed"

SimplePipeline

A SimplePipeline is a lightweight alternative to Pipeline for workflows with at most one expensive element — a single DataFit or Validation. It runs fire-and-forget and returns a flat result containing parameter_values, cost, and (for validation) summary_stats. Submit and poll it through client.simple_pipeline.

Building the config

SimplePipeline inherits everything from Pipeline and adds client-side validation that rejects configs with more than one expensive element:

import ionworks_schema as iws

objective = iws.objectives.CurrentDriven(
    data_input="file:path/to/discharge.csv", options={"model": "SPM"}
)
pipeline = iws.SimplePipeline(
    elements={
        "initial_params": iws.direct_entries.DirectEntry(
            parameters={"Negative particle diffusivity [m2.s-1]": 2e-14},
        ),
        "fit": iws.DataFit(
            objectives={"cycle": objective},
            parameters={
                "Negative particle diffusivity [m2.s-1]": iws.Parameter(
                    "Negative particle diffusivity [m2.s-1]",
                    bounds=(1e-14, 1e-13),
                    initial_value=2e-14,
                )
            },
            cost=iws.costs.RMSE(),
            optimizer=iws.parameter_estimators.ScipyDifferentialEvolution(
                maxiter=10
            ),
        ),
    },
    name="My Fit",
)

config = pipeline.to_config()

If you pass more than one DataFit or Validation element, SimplePipeline raises a ValueError immediately — no need to wait for a server-side rejection.

Submitting and polling

from ionworks import Ionworks

client = Ionworks()

# Submit — pass the schema instance directly (a dict from .to_config() also works)
sp = client.simple_pipeline.create(pipeline, name=pipeline.name)
# sp.status == "pending"

# Wait for completion (polls automatically)
result = client.simple_pipeline.wait_for_completion(sp.id, timeout=600)

# Read results
print(result.result["parameter_values"])
# {"Negative particle diffusivity [m2.s-1]": 5.3e-14}
print(result.result["cost"])

client.simple_pipeline.create() mirrors client.pipeline.create() — it accepts either an iws.SimplePipeline schema instance or the dict returned by .to_config(). Prefer the schema instance: you don’t need to call .to_config() yourself, and shape errors surface locally when you build the schema object. A raw dict is forwarded as-is, so a malformed dict is only rejected server-side as an HTTP 422.

Validation pipelines

SimplePipeline also supports a single Validation element. The result includes summary_stats alongside parameter_values.

objective = iws.objectives.CurrentDriven(
    data_input="file:path/to/cycle.csv", options={"model": "SPM"}
)
validation_pipeline = iws.SimplePipeline(
    elements={
        "validate": iws.Validation(
            objectives={"cycle": objective},
        ),
    },
    name="Validate fitted model",
)

sp = client.simple_pipeline.create(
    validation_pipeline, name=validation_pipeline.name
)
result = client.simple_pipeline.wait_for_completion(sp.id, timeout=600)
print(result.result["summary_stats"])

End-to-end example

import pybamm
import ionworks_schema as iws
from ionworks import Ionworks

client = Ionworks()

pipeline = iws.Pipeline(
    {
        "known": iws.direct_entries.DirectEntry(
            parameters={"Ambient temperature [K]": 298.15},
        ),
        "fit": iws.DataFit(
            objectives={
                "1C": iws.objectives.CurrentDriven(
                    data_input="file:examples/data/chen_synthetic_1C/time_series.csv",
                    options={"model": pybamm.lithium_ion.SPMe()},
                ),
            },
            parameters={
                "Negative particle diffusivity [m2.s-1]": iws.Parameter(
                    "Negative particle diffusivity [m2.s-1]",
                    initial_value=2e-14,
                    bounds=(1e-14, 1e-13),
                ),
            },
            cost=iws.costs.RMSE(),
            optimizer=iws.optimizers.DifferentialEvolution(),
        ),
    },
    name="SPMe diffusivity fit",
)

submission = client.pipeline.create(pipeline)
client.pipeline.wait_for_completion(submission.id)

result = client.pipeline.result(submission.id)
print(result.element_results["fit"])

For more end-to-end examples (entry-only, calculation-only, datafit, validation), see packages/ionworks-api/examples/pipeline/ in the SDK repo.