Python API client

Install and configure the ionworks-api Python package: authentication, dataframe backend, retries, and sub-clients reference

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

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 environment or .env file
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 .env file for credential management.

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
• Only GET and DELETE requests are retried. POST and PATCH requests are not retried to prevent duplicate operations.

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	Core Concepts 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
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
Jobs	client.job	Canceling jobs

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.