# Cell Instances

A cell instance represents a single physical cell. Every instance belongs to a
{doc}`cell specification <cell_specifications>`, which defines the cell type.
Instances carry per-cell metadata such as manufacturing date and measured
electrode properties, and can belong to a batch (manufacturing lot).

## Batches

A batch is a manufacturing lot: one production run of one specification. It is
its own record, so lot-level facts (manufacture date, notes, datasheet
properties) live in one place rather than on every cell. Batch names are unique
within a specification, compared case-insensitively.

```python
batch = client.cell_batch.create_or_get(
    cell_spec.id,
    {"name": "BATCH-2024-001", "date_manufactured": "2024-01-15"},
)

batches = client.cell_batch.list(cell_spec.id)  # paginated
batch = client.cell_batch.get(batch.id)  # includes instance_count
client.cell_batch.update(batch.id, {"notes": "Passed incoming QC"})
client.cell_batch.delete(batch.id)  # unlinks its cells, keeps them
```

## Creating an instance

Provide the parent specification ID and a metadata dictionary. Pass `batch_id`
to file the cell under a batch of the same specification:

```python
cell_instance = client.cell_instance.create(
    cell_spec.id,
    {
        "name": "NCM622-GR-001",
        "batch_id": batch.id,
        "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:

```python
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:

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

Narrow to one batch with `batch_id`:

```python
lot = client.cell_instance.list(cell_spec.id, batch_id=batch.id)
```

## Retrieving an instance

Fetch by ID:

```python
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:

```python
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:

```python
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

```python
updated = client.cell_instance.update(
    instance_id,
    {
        "batch_id": other_batch.id,
    },
)

# Remove the cell from its batch
client.cell_instance.update(instance_id, {"batch_id": None})
```

## Deleting an instance

```python
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
{doc}`cell_measurements`.