Cell Instances

A cell instance represents a single physical cell. Every instance belongs to a cell specification, which defines the cell type. Instances carry per-cell metadata such as batch number, manufacturing date, and measured electrode properties.

Creating an instance

Provide the parent specification ID and a metadata dictionary:

cell_instance = client.cell_instance.create(
    cell_spec.id,
    {
        "name": "NCM622-GR-001",
        "batch": "BATCH-2024-001",
        "date_manufactured": "2024-01-20",
        "measured_properties": {
            "cathode": {"loading": {"value": 12.1, "unit": "mg/cm**2"}},
            "anode": {"loading": {"value": 6.4, "unit": "mg/cm**2"}},
        },
    },
)
print(cell_instance.id)

As with specifications, create_or_get() avoids duplicates when re-running scripts:

cell_instance = client.cell_instance.create_or_get(cell_spec.id, {
    "name": "NCM622-GR-001",
    # ...
})

Listing instances

List all instances that belong to a specification:

instances = client.cell_instance.list(cell_spec.id)
for inst in instances:
    print(inst.name)

Retrieving an instance

Fetch by ID:

instance = client.cell_instance.get(instance_id)

Full details

detail() composes flat API endpoints in parallel to return the instance together with its measurements (including steps, cycles, and time-series data). Use the include_* flags to skip heavy data you don’t need:

detail = client.cell_instance.detail(instance_id)
# specification_id is a foreign key — fetch the full
# spec if needed:
spec = client.cell_spec.get(detail.specification_id)

# Skip time series for a faster response:
detail = client.cell_instance.detail(
    instance_id, include_time_series=False
)

Listing instances with measurements

Use flat CRUD composition to list instances and their measurements:

instances = client.cell_instance.list(cell_spec.id)
for inst in instances:
    measurements = client.cell_measurement.list(inst.id)
    print(f"{inst.name}: {len(measurements)} measurements")

Updating an instance

updated = client.cell_instance.update(instance_id, {
    "batch": "BATCH-2024-002",
})

Deleting an instance

client.cell_instance.delete(instance_id)

Note

Deleting an instance also removes all of its measurements.

Next steps

Once you have cell instances, upload experimental data in Cell Measurements.