Python API

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.

Data references in pipelines

Use these prefixes to reference data sources in pipeline configs:

Prefix	Example	Description
`db:`	`"db:measurement-id"`	Reference an uploaded measurement by ID
`file:`	`"file:data.csv"`	Load a local CSV file
`folder:`	`"folder:data_dir/"`	Load from a local directory

For inline DataFrames in pipeline configs, there is a 1,000-row limit. Upload larger datasets as measurements first, then reference them with db:measurement-id.

The folder: scheme expects a directory containing time_series and steps files. Both .parquet and .csv are supported, and parquet is preferred when both are present. For example, a folder with time_series.parquet and steps.parquet (or .csv) loads correctly.

PyBaMM model support

You can hand an objective a PyBaMM model object directly instead of naming a built-in model. It is serialized for you when the config is built — there is no registration step and no string name to look up.

import pybamm
import ionworks_schema as iws

objective = iws.objectives.CurrentDriven(
    data_input="path/to/discharge.csv",
    options={"model": pybamm.lithium_ion.DFN()},
)

Model options travel with the object, so a configured model arrives configured:

model = pybamm.lithium_ion.DFN(options={"thermal": "lumped"})

objective = iws.objectives.CurrentDriven(
    data_input="path/to/discharge.csv",
    options={"model": model},
)

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, ArrayDataFit, 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, ArrayDataFit, 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"])

Like client.pipeline.wait_for_completion, this also accepts poll_interval (seconds between polls, default 2), verbose (print status updates, default True), and raise_on_failure (default True; pass False to get the failed response back instead of raising) keyword arguments, and returns once the run reaches a terminal status — completed, failed, or canceled. 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.

Listing, filtering, and sorting

list returns a paginated response with items, count, and total. String filters accept either an exact value or an operator-prefixed expression such as ilike.%foo% (case-insensitive contains) or in.(completed,failed) (match any of a set).

# Newest 25 simple pipelines in the default project
page = client.simple_pipeline.list(limit=25)

# Only currently active runs
active = client.simple_pipeline.list(status="in.(pending,running)")

# Name contains "diffevo" (case-insensitive)
matches = client.simple_pipeline.list(name="ilike.%diffevo%")

# Created in the last week, oldest first
recent = client.simple_pipeline.list(
    created_at_gt="2026-05-08",
    created_at_lt="2026-05-15",
    order_by="created_at",
    order="asc",
)

Execution options

data_fit elements in simple pipelines are evaluated in parallel using the same distributed worker pool as regular pipelines. No extra configuration is required — set optimizer.population_size as usual and the server fans the population evaluations out across workers.

Pass an options dict to create to control runtime execution behavior for the submitted pipeline. Options are submission metadata — they affect how the server runs the job but are not stored as part of the pipeline config.

Option	Type	Default	Effect
`live_progress_updates`	`bool \| None`	`None` (worker picks a sensible default for the job type)	When `True`, the worker writes checkpoint progress to the database during execution so you can poll intermediate progress. When `False`, checkpoints are skipped for better performance.

sp = client.simple_pipeline.create(
    config,
    name="NMC622 diffusivity fit",
    options={"live_progress_updates": False},  # skip checkpointing for speed
)

You can also embed options (along with project_id, name, or description) directly in the config dict — create lifts them out of the config before submission. Arguments passed explicitly to create take precedence over values found in the config.

config = {
    "options": {"live_progress_updates": True},
    "elements": { ... },
}

sp = client.simple_pipeline.create(config)

Updating, cancelling, and deleting

# Rename or add a description (PATCH — at least one field is required)
client.simple_pipeline.update(sp.id, name="Renamed", description="notes")

# Cancel a running pipeline
client.simple_pipeline.cancel(sp.id)

# Permanently delete the pipeline, its job, and stored config
client.simple_pipeline.delete(sp.id)

Handling errors

from ionworks.errors import IonworksError

try:
    result = client.simple_pipeline.wait_for_completion(sp.id)
except TimeoutError:
    # Still running after the timeout — fetch the latest status to decide
    current = client.simple_pipeline.get(sp.id)
    print(f"Still {current.status}")
except IonworksError as e:
    # Pipeline ended in "failed" — the message includes the server error
    print(e)

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.

Get Started

Quickstarts

Core Concepts

Operate

Data

Build

Pipelines

Simulate

Optimize

Submitting a pipeline

Serializing a pipeline to JSON

Overriding submission metadata

Data references in pipelines

PyBaMM model support

Waiting for completion

Retrieving results

Element metadata

Data-fit parameter trace

Data-fit model-vs-data plot data

Listing pipelines

Getting a single submission

SimplePipeline

Building the config

Submitting and polling

Listing, filtering, and sorting

Execution options

Updating, cancelling, and deleting

Handling errors

Validation pipelines

End-to-end example

​Submitting a pipeline

​Serializing a pipeline to JSON

​Overriding submission metadata

​Data references in pipelines

​PyBaMM model support

​Waiting for completion

​Retrieving results

​Element metadata

​Data-fit parameter trace

​Data-fit model-vs-data plot data

​Listing pipelines

​Getting a single submission

​SimplePipeline

​Building the config

​Submitting and polling

​Listing, filtering, and sorting

​Execution options

​Updating, cancelling, and deleting

​Handling errors

​Validation pipelines

​End-to-end example

Submitting a pipeline

Serializing a pipeline to JSON

Overriding submission metadata

Data references in pipelines

PyBaMM model support

Waiting for completion

Retrieving results

Element metadata

Data-fit parameter trace

Data-fit model-vs-data plot data

Listing pipelines

Getting a single submission

SimplePipeline

Building the config

Submitting and polling

Listing, filtering, and sorting

Execution options

Updating, cancelling, and deleting

Handling errors

Validation pipelines

End-to-end example