Python API client

The ionworks-api Python package provides a programmatic interface for managing resources, running simulations, submitting pipelines, and uploading data in Ionworks Studio.

Driving Ionworks from a coding agent? The Ionworks Agentic Toolkit ships SDK-aware skills for Claude Code, Codex, and other agents — including an install skill that runs through this page’s setup for you.

Installation

Install the package from the repository:

pip install ionworks-api

Authentication

Get your API key from the Ionworks account settings and configure it:

from ionworks import Ionworks

# Option 1: Environment variable (recommended)
# Set IONWORKS_API_KEY in your shell environment before constructing the client
client = Ionworks()

# Option 2: Direct configuration
client = Ionworks(api_key="your_key")

# Option 3: Custom timeout and retry settings
client = Ionworks(
    timeout=30,       # Request timeout in seconds (default: 10)
    max_retries=3     # Max retries on failure (default: 5)
)

Never commit API keys to version control. Use environment variables or a secrets manager for credential management.

Starting in ionworks-api 0.10.0, importing ionworks no longer auto-loads a .env file. Set IONWORKS_API_KEY in your shell environment, load the .env file yourself (for example with python-dotenv) before constructing the client, or pass api_key= explicitly to Ionworks(...).

Verify your API key

Use client.whoami() to confirm which user and organization the configured API key resolves to. This is the recommended way to debug 401/403 errors, or to check why you’re seeing data from the wrong organization.

me = client.whoami()
print(me["email"], me["authorized_organization"])
# [email protected] {'id': 'org_abc123', 'name': 'Acme Battery'}

The response has two organization fields and the distinction matters:

authorized_organization — the org this request is authorized as. For SDK calls, this is the org the configured API key was issued for, and is the source of truth for permission checks on every request the client makes. It’s None if no org context could be resolved.
organizations — the user’s full membership list (every org they belong to). This is a different question and is not what permission checks run against.

If the id or name in authorized_organization doesn’t match what you expect, the wrong key is in use — regenerate one for the correct org from your account settings.

Default project

Most sub-clients (pipelines, studies, optimizations, cell specifications, …) operate within a project. Rather than threading a project_id through every call, you can configure a default once on the client. Sub-client methods that take a project_id argument fall back to this default when one isn’t passed explicitly. The client resolves the default in this order:

The project_id= argument passed to Ionworks(...).
The IONWORKS_PROJECT_ID environment variable.
Otherwise, no default is set — methods that need a project will raise ValueError unless project_id is passed at the call site.

# Option 1: Environment variable (recommended)
# Set IONWORKS_PROJECT_ID in your environment or .env file
client = Ionworks()

# Option 2: Pass to the client constructor
client = Ionworks(project_id="your-project-id")

# Override on a per-call basis when needed
client.study.list(project_id="other-project-id")

You can find your project ID in the URL of the project settings page: https://app.ionworks.com/dashboard/projects/<project-id>/settings.

The PROJECT_ID environment variable is still accepted for backwards compatibility but is deprecated. Set IONWORKS_PROJECT_ID instead — using the old name emits a DeprecationWarning and will stop working in a future release.

Environment variables

The client reads the following variables from your shell environment when constructed. .env files are not loaded automatically — populate the environment yourself (for example by sourcing the file, or by calling python-dotenv) before constructing the client.

Variable	Required	Default	Description
`IONWORKS_API_KEY`	Yes	—	API key from your account settings.
`IONWORKS_API_URL`	No	`https://api.ionworks.com`	API base URL.
`IONWORKS_PROJECT_ID`	For project-scoped calls	—	Default project ID for sub-client methods.
`IONWORKS_DATAFRAME_BACKEND`	No	`polars`	DataFrame backend: `polars` or `pandas`.

DataFrame backend

By default, the client returns data as polars DataFrames. You can switch to pandas if your workflow requires it.

# Option 1: Set via constructor
client = Ionworks(dataframe_backend="pandas")

# Option 2: Set via environment variable
# IONWORKS_DATAFRAME_BACKEND=pandas

# Option 3: Set at runtime
from ionworks import set_dataframe_backend, get_dataframe_backend

set_dataframe_backend("pandas")
print(get_dataframe_backend())  # "pandas"

All methods that return DataFrames (time series, steps, cycles) respect this setting.

Timeout and retry behavior

The client automatically retries failed requests on connection errors, timeouts, and server errors (5xx). By default:

Requests time out after 10 seconds
Failed requests retry up to 5 times with exponential backoff
Dropped connections (the server closed the socket before the request reached the application — common on reused keep-alive connections) are retried for all methods, including POST and PATCH. The request never reached the server, so resending is safe.
Read timeouts and 5xx responses are only retried for idempotent methods (GET and DELETE). The server may have already processed a POST or PATCH, so resubmitting could duplicate the operation.

You can customize these settings:

# Longer timeout for large uploads
client = Ionworks(timeout=60)

# Disable retries
client = Ionworks(max_retries=0)

Sub-clients

The Ionworks client exposes domain-specific sub-clients:

Sub-client	Access	Documentation
Projects	`client.project`	Projects API
Models	`client.model`	Build API
Parameterized models	`client.parameterized_model`	Build API
Studies	`client.study`	Simulate API
Protocols	`client.protocol`	Simulate API
Simulations	`client.simulation`	Simulate API
Pipelines	`client.pipeline`	Simulate API
Simple pipelines	`client.simple_pipeline`	Simulate API
Optimizations	`client.optimization`	Optimize API
Cell specifications	`client.cell_spec`	Uploading data
Cell instances	`client.cell_instance`	Uploading data
Cell measurements	`client.cell_measurement`	Measurements
Sites	`client.site`	Lab view
Cyclers	`client.cycler`	Lab view
Channels	`client.channel`	Lab view
Lab occupancy	`client.lab`	Lab view
Analyses	`client.analysis`	Analyses
Materials	`client.material`	Materials & property datasets
Material property datasets	`client.material_property_dataset`	Materials & property datasets
Jobs	`client.job`	Canceling jobs
Web app URLs	`client.urls`	Web app URL helpers

Discovering the API

client.capabilities() and client.schema(name) return the same content the discover-api agent skill is built on. Use them from a notebook or script to introduce yourself — or a coding agent you’re scripting against — to the platform’s data hierarchy and to fetch the authoritative JSON Schemas for measurements and UCP protocols.

caps = client.capabilities()
print(caps["domain_context"]["hierarchy"])
# organization -> project -> cell_specification -> cell_instance
# -> cell_measurement -> [time_series, steps, cycles, analysis] ...

# Standard time-series column names, required fields, sign conventions
data_schema = client.schema("data")

# Full UCP JSON Schema plus runnable examples
protocol_schema = client.schema("protocol")

capabilities() also returns pointers to the OpenAPI spec (/openapi.json) and per-resource JSON Schema endpoints under caps["schemas"], so agents can fetch the exact shape of any create/update payload before calling it.

Coding agents driving Ionworks should call client.capabilities() and client.schema(name) before generating request bodies — the responses reflect the running server, so agents never guess at endpoint shapes or column names that may have drifted.

Web app URL helpers

client.urls builds links to resource pages in the Ionworks web app (Ionworks Studio) without requiring you to hand-construct URLs from entity IDs. Use it to surface clickable links from notebooks, scripts, dashboards, or Slack/email reports so collaborators can jump straight to the resource in the web app. Every helper runs entirely locally — no network call — except client.urls.simulation(), which fetches the simulation once when parameterized_model_id isn’t supplied (see below).

client = Ionworks(project_id="proj_abc")

client.urls.study("study_xyz")
# https://app.ionworks.com/dashboard/projects/proj_abc/studies/study_xyz

client.urls.parameterized_model("pm_123")
# https://app.ionworks.com/dashboard/projects/proj_abc/parameterized-models/pm_123

Each helper takes the resource’s own ID plus whatever parent IDs the route requires. project_id is optional — it falls back to the default project configured on the client.

Helper	Returns a link to
`client.urls.project(project_id=None)`	Project landing page (its studies list).
`client.urls.study(study_id, project_id=None)`	Study detail page.
`client.urls.model(model_id, project_id=None)`	Model detail page.
`client.urls.parameterized_model(parameterized_model_id, project_id=None)`	Parameterized model detail page.
`client.urls.simulation(simulation_id, parameterized_model_id=None, project_id=None)`	Simulation detail page (nested under its parameterized model).
`client.urls.protocol(protocol_id, project_id=None)`	Protocol detail page.
`client.urls.pipeline(pipeline_id, project_id=None)`	Pipeline detail page.
`client.urls.optimization(optimization_id, project_id=None)`	Optimization detail page.
`client.urls.material(material_id, project_id=None)`	Material detail page.
`client.urls.cell_specs(project_id=None)`	Cell specifications list page.
`client.urls.cell_instances(spec_id, project_id=None)`	Cell instances list page nested under a spec.
`client.urls.measurement(measurement_id, project_id=None)`	Measurement detail page.

Simulation URLs

A simulation’s web-app route is nested under its parameterized model. If you already know the parameterized_model_id, pass it in to avoid a network call:

client.urls.simulation("sim_1", parameterized_model_id="pm_123")

Otherwise the helper fetches the simulation to look it up:

# One GET to client.simulation.get(simulation_id), then builds the URL.
client.urls.simulation("sim_1")

If the simulation has no parameterized_model_id (e.g. a study-only simulation), the helper raises ValueError and you must pass the parent explicitly.

Canceling jobs

You can cancel running jobs (simulations, pipelines, and optimizations) using the Python API. Each job has a unique ID that you can use to cancel it.

# Cancel a job by ID
client.job.cancel(job_id="job_abc123")

Cancelling a parent job automatically cancels all of its child jobs. For example, cancelling a pipeline cancels all of its running elements.

Resubmitting a failed pipeline

If a pipeline stops because its first failed element could not be submitted (error_code = SUBMISSION_FAILED), you can resubmit it without rebuilding the configuration. Completed elements are preserved; execution resumes from the failed element. The Python client does not yet expose a resubmit method, so call the REST endpoint directly as a temporary workaround. Resubmission goes through the generic jobs endpoint, and a pipeline is identified by its job ID — the same ID you pass to client.pipeline.get(...):

curl -X POST \
  -H "Authorization: Bearer $IONWORKS_API_KEY" \
  https://api.ionworks.com/jobs/{pipeline_id}/resubmit

Resubmission only applies to SUBMISSION_FAILED errors. For execution timeouts or configuration mistakes, create a new pipeline with the corrected configuration. For internal errors, wait briefly and create a new pipeline if the issue persists. See Handling pipeline failures for details.

Retrieving job metadata

Standard job-detail responses strip fields that can grow large — submitted configs, full result payloads, and serialized PyBaMM models — so listing and polling stay fast even for pipelines or optimizations with heavy inline data. When you actually need those fields, fetch them with client.job.get_metadata:

# Fetch the full, untruncated metadata for a job
metadata = client.job.get_metadata(job_id="job_abc123")

# Validation payloads, when present
results = metadata.get("validation_results")
plot_config = metadata.get("validation_plot_config")

Use this when you need to:

Re-run a job from its original submitted config without keeping a local copy.
Audit the exact inputs that produced a result.
Read large result blobs — for example, optimization traces, or the validation_results and validation_plot_config produced by pipeline validations — that aren’t included in the default job response.

The returned object is a plain dict parsed from the job’s metadata.json.gz blob. If a job has no metadata file (for example, it failed before writing one) the call raises an error — wrap it in a try/except if you’re iterating over many jobs.

For pipelines, client.pipeline.result(pipeline_id) is still the easiest way to get parsed, fitted parameter values. Use client.job.get_metadata when you need the raw, unparsed payload backing a job.

Get Started

Core Concepts

Data

Build

Pipelines

Simulate

Optimize

Installation

Authentication

Verify your API key

Default project

Environment variables

DataFrame backend

Timeout and retry behavior

Sub-clients

Discovering the API

Web app URL helpers

Simulation URLs

Canceling jobs

Resubmitting a failed pipeline

Retrieving job metadata

​Installation

​Authentication

​Verify your API key

​Default project

​Environment variables

​DataFrame backend

​Timeout and retry behavior

​Sub-clients

​Discovering the API

​Web app URL helpers

​Simulation URLs

​Canceling jobs

​Resubmitting a failed pipeline

​Retrieving job metadata

Installation

Authentication

Verify your API key

Default project

Environment variables

DataFrame backend

Timeout and retry behavior

Sub-clients

Discovering the API

Web app URL helpers

Simulation URLs

Canceling jobs

Resubmitting a failed pipeline

Retrieving job metadata