Cell Batch

Client for managing cell batches (manufacturing lots of one cell specification).

For usage examples and guides, see Data API on docs.ionworks.com.

Cell batch client for managing manufacturing lots.

This module provides the CellBatchClient for creating, reading, updating, and deleting cell batches. A batch is a manufacturing lot — one production run of one cell specification — that cell instances join through their batch_id.

class ionworks.api.cell_batch.CellBatchClient(client: Any)

Bases: object

Client for managing cell batches (manufacturing lots).

__init__(client: Any) → None

Initialize the CellBatchClient.

Parameters:

client (Any) – The HTTP client instance used for API calls.

get(batch_id: str) → CellBatch

Get a specific cell batch by ID.

Parameters:

batch_id (str) – The ID of the cell batch.

Returns:

The cell batch, including its current instance_count.

Return type:

CellBatch

list(cell_spec_id: str, limit: int | None = None, offset: int | None = None, *, name: str | None = None, name_exact: str | None = None) → PaginatedList[CellBatch]

List the batches of a cell specification.

Always returns a PaginatedList which behaves like a regular list. Use limit and offset to control the page.

Parameters:

• cell_spec_id (str) – The ID of the cell specification whose batches to list.

• limit (int | None, optional) – Maximum number of batches to return per page.

• offset (int | None, optional) – Number of batches to skip for pagination.

• name (str | None, optional) – Case-insensitive substring match on batch name.

• name_exact (str | None, optional) – Exact match on batch name. Takes precedence over name.

Returns:

One page of batches belonging to the specification, with .total for the full count.

Return type:

PaginatedList[CellBatch]

create(cell_spec_id: str, data: dict[str, Any]) → CellBatch

Create a new batch under a cell specification.

Parameters:

• cell_spec_id (str) – The ID of the cell specification the lot was manufactured to.

• data (dict[str, Any]) – Batch fields. name is required and must be unique within the specification (compared case-insensitively). Optional: notes (str), date_manufactured (ISO date, "YYYY-MM-DD"), and properties (dict; numeric values use the Quantity format {"value": ..., "unit": ...}).

Returns:

The newly created batch.

Return type:

CellBatch

Raises:

IonworksError – With error_code == "CONFLICT" (HTTP 409) if the specification already has a batch of that name; detail["existing_id"] names it. Use create_or_get() to resolve that automatically.

Examples

Create a lot, then file a new cell under it:

batch = client.cell_batch.create(
    spec.id,
    {"name": "LOT-2025-Q1", "date_manufactured": "2025-01-15"},
)
client.cell_instance.create(
    spec.id, {"name": "Cell 001", "batch_id": batch.id}
)

create_or_get(cell_spec_id: str, data: dict[str, Any]) → CellBatch

Create a new batch, or get the existing one on a name conflict.

Parameters:

• cell_spec_id (str) – The ID of the cell specification the lot was manufactured to.

• data (dict[str, Any]) – Batch fields, as for create(). On a conflict the existing batch is returned unchanged; the other fields are not applied.

Returns:

The batch (newly created or existing).

Return type:

CellBatch

Raises:

ValueError – If the create reported a duplicate but the existing batch could not be found by id or name.

update(batch_id: str, data: dict[str, Any]) → CellBatch

Update an existing cell batch.

Parameters:

• batch_id (str) – The ID of the cell batch to update.

• data (dict[str, Any]) – The fields to change (partial update): any of name, notes, date_manufactured, and properties. Renaming a batch renames it for every member instance, since they reference it by id.

Returns:

The updated batch.

Return type:

CellBatch

delete(batch_id: str) → None

Delete a cell batch by ID.

Member cell instances are kept and unlinked (their batch_id becomes None); deleting a lot never deletes its cells.

Parameters:

batch_id (str) – The ID of the cell batch to delete.