Measurements

A cell measurement represents a single experiment or test performed on a cell instance. Every measurement has a measurement_type that determines what data it stores and how you create it.

Measurement types

Type	Stores	Typical use
`time_series`	High-resolution cycling data with voltage, current, and time columns. Includes auto-generated step and cycle summaries.	Battery cycling tests, EIS measurements, charge/discharge experiments
`properties`	Key-value pairs with optional units. No file upload.	Manual measurements like thickness, weight, internal resistance
`file`	One or more uploaded files (images, PDFs, numpy arrays, etc.) attached to the record.	Microscopy images, SEM photos, post-mortem analysis documents

Common fields

Every measurement — regardless of type — accepts these optional metadata fields:

Field	Description
`name`	Name for the measurement
`protocol_id`	The protocol (experiment template) this test ran. Must belong to the same project as the measurement. Preferred over the free-form `protocol` dict — see recording what a measurement ran.
`protocol.name`	Protocol description (free-form; omit when `protocol_id` is set)
`protocol.ambient_temperature_degc`	Test temperature
`test_setup`	`cycler`, `operator`, `lab`, `channel_number`
`start_time`	ISO 8601 start time, e.g. `"2026-03-15T09:30:00Z"`
`channel_id`	ID of the physical channel the test ran on. Must belong to the same project as the measurement.
`program_id`	Optional program this test belongs to. Copied automatically from the linked planned measurement, or set directly on the measurement. Must reference a program in the same organization.
`estimated_end_time`	ISO 8601 estimate of when the test will finish. Optional. Shown on channel cards in the Lab view while the test is running so you can see when a channel is expected to free up.
`notes`	Free-form notes about the test

Recording what a measurement ran

Two fields describe the test, and they are not interchangeable:

Field	What it is
`protocol_id`	A reference to a real protocol — the executable definition
`protocol`	A free-form dict of the conditions the run happened under

Prefer protocol_id. It points at a definition the platform can act on: resolve to a name, link to in the app, simulate, or convert to a cycler file. The dict is unvalidated text, so two runs of the same test can spell it differently and nothing reconciles them. Use the protocol dict when you have no full protocol. That is common and not a failure: data imported from a cycler export often records “1C discharge at 25 °C” and nothing reconstructable into an executable definition. Recording what you know beats dropping it. Setting both is the best record — protocol_id for what the run was supposed to execute, the dict for the conditions it actually ran under. One protocol serves many runs at different temperatures, and only the dict captures which.

client.cell_measurement.create(
    instance_id,
    {
        "measurement": {
            "name": "udds_25degc",
            "protocol_id": "experiment-template-id",
            "protocol": {"ambient_temperature_degc": 25.0, "c_rate": 1.0},
        },
        "time_series": df,
    },
)

When you set protocol_id, do not put a name in the protocol dict. The protocol already has one, the two can disagree, and the app suppresses the dict’s name once protocol_id is set.

protocol_id can also be attached later, once the protocol a run executed is known, via client.cell_measurement.update().

Time series

Time series is the default measurement type. It carries high-resolution cycling data and auto-generates step and cycle summaries on upload. The time series DataFrame must follow the data format — recognized columns include Time [s], Voltage [V], Current [A], Step count, and Cycle count.

import pandas as pd

time_series = pd.DataFrame({
    "Time [s]": [0, 1, 2, 3, 4, 5],
    "Voltage [V]": [3.0, 3.2, 3.5, 3.8, 4.0, 4.2],
    "Current [A]": [0.002, 0.002, 0.002, 0.002, 0.002, 0.002],
    "Step count": [0, 0, 0, 1, 1, 1],
    "Cycle count": [0, 0, 0, 0, 0, 0],
})

bundle = client.cell_measurement.create(
    cell_instance.id,
    {"measurement": {"name": "Formation Cycle 1"}, "time_series": time_series},
)

create() returns a MeasurementBundle containing the measurement record plus metadata like steps_created. See uploading data for the full upload workflow — protocol and test-setup metadata, on-machine validation, and idempotent create_or_get — and reading data to fetch a measurement back with its full time series, steps, and cycles.

Properties

Properties measurements store key-value pairs directly in the record — no file upload. Use them for manual or one-off measurements like thickness, weight, or internal resistance. Properties-specific fields:

Field	Description
`properties`	Key-value pairs. Use the quantity format for numeric values. Plain strings and numbers are also allowed.

measurement = client.cell_measurement.create_properties(
    cell_instance.id,
    name="Post-formation properties",
    properties={
        "thickness": {"value": 0.52, "unit": "mm"},
        "weight": {"value": 45.3, "unit": "g"},
        "internal_resistance": {"value": 12.5, "unit": "mOhm"},
        "visual_condition": "No visible damage",
    },
    notes="Measured after formation cycling",
)

You can include any of the common metadata fields (protocol, test_setup, start_time, notes) alongside the properties.

create_properties returns a Measurement directly, not a MeasurementBundle. Properties measurements have no steps or file uploads, so the bundle wrapper isn’t needed.

File

File measurements attach files (images, PDFs, numpy arrays, or any other file type) to a measurement record. Useful for microscopy images, SEM photos, X-ray CT scans, or post-mortem analysis documents. File-specific fields:

Field	Description
`filepaths`	List of local file paths to upload
`validate_images`	When `True`, validates file headers match the extension before upload
`file_metadata`	Populated automatically by the server after upload (MIME types, dimensions, etc.) — read-only

bundle = client.cell_measurement.create_file(
    cell_instance.id,
    name="Post-cycling SEM images",
    filepaths=[
        "images/anode_surface_1000x.png",
        "images/cathode_cross_section_500x.png",
    ],
    notes="SEM images taken after 500 cycles",
)

To enable client-side image validation:

bundle = client.cell_measurement.create_file(
    cell_instance.id,
    name="Electrode images",
    filepaths=["photo.png", "scan.tiff"],
    validate_images=True,
)

To access files from an existing file measurement:

# List filenames in the measurement
filenames = client.cell_measurement.list_files(measurement_id)

# Download file contents directly
files = client.cell_measurement.download_files(measurement_id)
for filename, content in files.items():
    print(f"{filename}: {len(content)} bytes")

File measurements use a signed URL upload flow internally. The client handles the multi-step process (initiate, upload, confirm) automatically.

Previewing files in Studio

When you open a file measurement in Studio, attached files are shown as a gallery beneath the measurement details:

Images (.png, .jpg, .webp, etc.) render as inline thumbnails. Click a thumbnail to open it in a full-screen lightbox.
Non-image files (PDFs, numpy arrays, CSVs, etc.) appear as cards with a download button.

This makes it easy to review SEM photos, X-ray CT scans, and other microscopy images directly in the browser without downloading them first.

Tags

Tags are free-form labels on a measurement, such as baseline, rpt, or batch-7, that you can filter, bulk-edit, and search by. Any measurement type can carry them. Tags belong to a project: suggestions and filters only see the tags used in that project. Tags match case-insensitively, and a new tag reuses the project’s existing spelling, so typing aged when Aged is already in use stores Aged. Surrounding whitespace is trimmed and duplicates are dropped. Each tag can be up to 50 characters, and each measurement can carry up to 50 tags.

In the app

Add tags on a measurement’s detail page, below Notes. Type to search the project’s existing tags, or press Enter to create a new one. Each change saves straight away, and removing a tag offers Undo.
Bulk-tag from the measurements list: select rows, or use Select all N matching, then choose Edit tags to add or remove tags across the selection.
Filter by clicking a tag chip in the Tags column, or with the tag filter, which matches measurements carrying any or all of the chosen tags.
Search for a tag in global search to find the measurements carrying it.

In the API

Pass tags when creating a measurement, or in a PATCH to /cell_measurements/{id}; a PATCH replaces the whole set. List endpoints accept repeatable tags_all (carries every tag) and tags_any (carries at least one) filters. GET /cell_measurements/tags?project_id=... lists a project’s tags with usage counts, most used first, and POST /cell_measurements/tags/bulk adds or removes tags on up to 1000 measurements at once.

# Tag at creation
client.cell_measurement.create_properties(
    cell_instance.id,
    name="Post-formation properties",
    properties={"thickness": {"value": 0.52, "unit": "mm"}},
    tags=["baseline", "batch-7"],
)

# Add or remove tags on many measurements without restating the rest
client.cell_measurement.add_tags([measurement_id_1, measurement_id_2], ["rpt"])
client.cell_measurement.remove_tags(measurement_id_1, ["baseline"])

# Find measurements across a project by tag
rpts = client.cell_measurement.list_by_project(project_id, tags_all=["rpt", "batch-7"])

# The project's tags, most used first
for usage in client.cell_measurement.list_tags(project_id):
    print(usage.tag, usage.usage_count)

list() for a single cell instance accepts the same tags_all / tags_any filters, and client.cell_measurement.update(measurement_id, {"tags": [...]}) replaces a measurement’s tags.

Get Started

Quickstarts

Core Concepts

Operate

Data

Build

Simulate

Optimize

Measurement types

Common fields

Recording what a measurement ran

Time series

Properties

File

Previewing files in Studio

Tags

In the app

In the API

Next steps

Uploading data

Reading data

​Measurement types

​Common fields

​Recording what a measurement ran

​Time series

​Properties

​File

​Previewing files in Studio

​Tags

​In the app

​In the API

​Next steps

Uploading data

Reading data

Measurement types

Common fields

Recording what a measurement ran

Time series

Properties

File

Previewing files in Studio

Tags

In the app

In the API

Next steps