Cell Instance

Client for managing cell instances.

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

Cell instance client for managing individual cell records.

This module provides the CellInstanceClient for creating, reading, updating, and deleting cell instances, which represent individual physical battery cells linked to a cell specification.

class ionworks.api.cell_instance.CellInstanceClient(client: Any)[source]

Bases: object

Client for managing cell instances.

__init__(client: Any) → None[source]

Initialize the CellInstanceClient.

Parameters:

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

get(cell_instance_id: str) → CellInstance[source]

Get a specific cell instance by ID.

list(cell_spec_id: str, limit: int | None = None, offset: int | None = None, *, name: str | None = None, name_exact: str | None = None, created_by_email: str | None = None, created_after: str | None = None, created_before: str | None = None, updated_after: str | None = None, updated_before: str | None = None, order_by: str | None = None, order: str | None = None, batch_id: str | None = None) → PaginatedList[CellInstance][source]

List cell instances for a specification with optional filtering.

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.

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

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

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

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

  • created_by_email (str | None, optional) – Case-insensitive substring match on the creator’s email.

  • created_after (str | None, optional) – ISO datetime; return instances created after this time.

  • created_before (str | None, optional) – ISO datetime; return instances created before this time.

  • updated_after (str | None, optional) – ISO datetime; return instances updated after this time.

  • updated_before (str | None, optional) – ISO datetime; return instances updated before this time.

  • order_by (str | None, optional) – Column to sort by ("name", "created_at", "updated_at").

  • order (str | None, optional) – Sort direction: "asc" or "desc".

  • batch_id (str | None, optional) – Return only instances in this cell batch (exact match on batch_id).

Returns:

All instances belonging to the specification.

Return type:

PaginatedList[CellInstance]

update(cell_instance_id: str, data: dict[str, Any]) → CellInstance[source]

Update an existing cell instance.

Parameters:

  • cell_instance_id (str) – The ID of the cell instance to update.

  • data (dict[str, Any]) – Dictionary containing the fields to update (partial update). Set batch_id to move the cell into a lot of its specification, or to None to remove it from its lot.

Returns:

The updated cell instance.

Return type:

CellInstance

Raises:

  • ValueError – If data contains the removed batch field. Nothing is sent.

  • IonworksError – With HTTP 400 if batch_id does not name a batch of this instance’s cell specification.

delete(cell_instance_id: str) → None[source]

Delete a cell instance by ID.

detail(cell_instance_id: str, include_steps: bool = True, include_cycles: bool = True, include_time_series: bool = True) → CellInstanceDetail[source]

Get full details for a cell instance.

Composes flat API endpoints in parallel to build the complete detail view. For each measurement, fetches steps/cycles and time series according to the include_* flags.

Parameters:

  • cell_instance_id (str) – The cell instance ID.

  • include_steps (bool, optional) – Whether to fetch step data for each measurement. Defaults to True.

  • include_cycles (bool, optional) – Whether to fetch cycle metrics for each measurement. Defaults to True.

  • include_time_series (bool, optional) – Whether to fetch time series for each measurement. Defaults to True.

Returns:

Instance metadata, specification foreign key, and a list of measurement details.

Return type:

CellInstanceDetail

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

Create a new cell instance under a specification.

Parameters:

  • cell_spec_id (str) – The ID of the parent cell specification.

  • data (dict[str, Any]) – Dictionary containing the cell instance data. name is required. To file the cell under a manufacturing lot, pass batch_id — the id of a batch of the same specification (see CellBatchClient).

Returns:

The newly created cell instance.

Return type:

CellInstance

Raises:

  • ValueError – If data contains the removed batch field. Nothing is sent.

  • IonworksError – With HTTP 400 if batch_id does not name a batch of cell_spec_id.

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

Create a new cell instance or get existing.

Parameters:

  • cell_spec_id (str) – The ID of the parent cell specification.

  • data (dict[str, Any]) – Dictionary containing the cell instance data.

Returns:

The cell instance (newly created or existing).

Return type:

CellInstance

Raises:

ValueError – If data contains the removed batch field. Nothing is sent.