Planned measurements

A planned measurement is a project-scoped record of a test you intend to run. A requester creates it as requested (with an estimated duration but no channel); a scheduler later assigns a channel and a [planned_start_time, planned_end_time) window, moving it to scheduled. Planned measurements never create or mutate a real cell measurement. When the real test starts, the actual cell_measurement links back to the plan and moves it to in_progress — the planned row stays as the request-and-schedule audit trail.

When to use it

Planned measurements are optional — you can still create measurements directly and set channel_id at run time as described in the Lab view. Use planned measurements when you want to:

Track a backlog of tests requested against a project or a specific cell specification.
Reserve future channel time so two schedulers don’t book the same channel and window.
Separate the request (from a scientist or PM) from the scheduling decision (from a lab operator).
Keep an audit trail of who requested and scheduled each test.

If you just have a single cycler and start tests ad hoc, keep linking measurements to channels directly and skip planned measurements.

Lifecycle

requested ──► scheduled ──► in_progress ──► completed
    │             │
    └── cancelled ┘

Status	Meaning
`requested`	A future test with no channel yet. Requires `estimated_duration_seconds`. This is what a requester creates.
`scheduled`	A scheduler has assigned a `channel_id` and a `[planned_start_time, planned_end_time)` reservation. Requires all three.
`in_progress`	Set automatically once the real `cell_measurement` starts and links to the plan. Carries `started_measurement_id`.
`completed`	Set once the linked real measurement finishes.
`cancelled`	Plan abandoned before completion. The row is kept as an audit trail.

Scheduling is fully manual — the scheduler picks the channel and times. There is no automatic optimizer. Reserving future channel time on a scheduled plan does not make the Lab view show the channel as occupied — only a running real measurement does that. A plan reserves the calendar; a cell_measurement reserves the current moment.

Fields

Field	Description
`name`	Human-readable name (required, unique within the project).
`status`	Defaults to `"requested"`. Create as `requested` or `scheduled`.
`estimated_duration_seconds`	Required for `requested` rows.
`channel_id`, `planned_start_time`, `planned_end_time`	Required for `scheduled` rows. `planned_end_time` must be after `planned_start_time`.
`cell_specification_id`	The cell specification a requester wants tested. Optional.
`cell_instance_id`	The concrete cell instance the test will run on. Usually set by the scheduler. If both `cell_specification_id` and `cell_instance_id` are set, the instance must belong to the specified spec.
`setup_duration_seconds`, `teardown_duration_seconds`	Operator setup and teardown time, in seconds. Default `0`.
`protocol`, `test_setup`, `notes`	Optional free-text planning metadata.
`started_measurement_id`	Set automatically when a real measurement links back to the plan.

Names are unique per project (case-insensitive). Creating a plan with a duplicate name raises IonworksError with error_code == "CONFLICT" (HTTP 409). Use create_or_get to make creation idempotent.

Requesting a measurement

Create a requested plan with no channel; supply an estimated duration and, optionally, the cell specification you want tested. The scheduler picks the concrete instance later.

from ionworks import Ionworks

client = Ionworks(project_id="your-project-id")

planned = client.planned_measurement.create({
    "name": "Formation cycling",
    "cell_specification_id": "cell-spec-id",
    "estimated_duration_seconds": 7200,
    "notes": "Run at 25 C",
})
# planned.status == "requested", planned.channel_id is None

Use create_or_get to make the request idempotent by name:

planned = client.planned_measurement.create_or_get({
    "name": "Formation cycling",
    "estimated_duration_seconds": 7200,
})

Scheduling onto a channel

Assign a channel and a time window with schedule — a convenience wrapper that moves a requested plan to scheduled.

planned = client.planned_measurement.schedule(
    "planned-measurement-id",
    channel_id="channel-id",
    planned_start_time="2026-07-21T09:00:00+00:00",
    planned_end_time="2026-07-21T11:00:00+00:00",
)
# planned.status == "scheduled"

You can also create a plan that starts already scheduled in one call:

planned = client.planned_measurement.create({
    "name": "RPT",
    "status": "scheduled",
    "channel_id": "channel-id",
    "planned_start_time": "2026-07-21T09:00:00+00:00",
    "planned_end_time": "2026-07-21T11:00:00+00:00",
})

Scheduling is rejected when the window would collide with something already on the channel. Pick a different channel or window and retry.

Rejection	When it triggers	Status
Overlapping scheduled plan	The window overlaps another non-cancelled `scheduled` plan on the same channel.	409
Overlapping active measurement	The window overlaps an active `cell_measurement` on the same channel. Active measurements with no `estimated_end_time` block scheduling by default.	409
Channel out of commission	The target channel has `out_of_commission = true`. Only new `scheduled` reservations are rejected — existing plans keep transitioning normally.	400
Missing required fields	A `scheduled` row without `channel_id`, `planned_start_time`, or `planned_end_time`, or `planned_end_time <= planned_start_time`.	400

Cancelling or completing an existing plan is always allowed, even after the channel goes out of commission.

Listing and filtering

list is project-scoped and returns a PaginatedList[PlannedMeasurement]. Filter by lifecycle status, channel, or name.

# The scheduler's queue: everything still requested
requested = client.planned_measurement.list(status="requested")

# The lab's calendar: scheduled plans, earliest first
scheduled = client.planned_measurement.list(
    status="scheduled",
    order_by="planned_start_time",
    order="asc",
)

# Everything on a specific channel
on_channel = client.planned_measurement.list(channel_id="channel-id")

# Paginate
page = client.planned_measurement.list(limit=25, offset=0)
print(page.count, page.total)

# Get one by id
planned = client.planned_measurement.get("planned-measurement-id")

Updating, cancelling, and deleting

# Partial update — edit notes or estimated duration in place
client.planned_measurement.update(
    "planned-measurement-id", {"notes": "Revised setup"}
)

# Cancel — keeps the row as an audit trail
client.planned_measurement.cancel("planned-measurement-id")

# Delete — removes the row entirely
client.planned_measurement.delete("planned-measurement-id")

To reschedule a plan, call schedule again with a new channel or window (or update the individual fields). The server re-runs the overlap and out-of-commission checks against the new values.

Linking a real measurement to a plan

You do not transition a plan to in_progress by hand. When the real run starts, create the cell_measurement with planned_measurement_id set — the backend links it and moves the plan to in_progress atomically.

measurement = client.cell_measurement.create(
    cell_instance_id,
    {
        "measurement": {
            "name": "Formation run",
            "channel_id": "channel-id",
            "planned_measurement_id": "planned-measurement-id",
        },
        "time_series": time_series,
    },
)

The link is rejected with HTTP 400 unless all of these hold:

The plan is scheduled.
The measurement is a time_series measurement and carries a channel_id (a planned_measurement_id with no channel_id is rejected).
The plan and measurement are in the same project and organization.
The measurement’s channel_id equals the plan’s channel_id.
If the plan has a cell_instance_id, the measurement must run on that same cell instance.

Two concurrent measurements can never both claim the same plan — the link is an atomic compare-and-set on status = scheduled, so the loser is left unlinked (and logged as a warning). After linking, channel occupancy on the Lab view is driven by the running cell_measurement. The planned row remains as the audit trail.

Permissions

Planned measurement endpoints reuse the existing cell_measurement permissions:

Action	Permission
List, get	`cell_measurement:read`
Create	`cell_measurement:create`
Update, schedule, cancel	`cell_measurement:update`
Delete	`cell_measurement:delete`

`project_id`

All client.planned_measurement.* methods accept an optional project_id. When omitted it falls back to the project_id configured on the Ionworks client (or the IONWORKS_PROJECT_ID env var). Methods raise ValueError if no project_id is available from any source.

Next steps

Lab view

Set up the sites, cyclers, and channels that planned measurements schedule onto.

Measurements

Create the real cell_measurement that links back to a scheduled plan.

Get Started

Core Concepts

Data

Build

Pipelines

Simulate

Optimize

When to use it

Lifecycle

Fields

Requesting a measurement

Scheduling onto a channel

Listing and filtering

Updating, cancelling, and deleting

Linking a real measurement to a plan

Permissions

`project_id`

Next steps

Lab view

Measurements

​When to use it

​Lifecycle

​Fields

​Requesting a measurement

​Scheduling onto a channel

​Listing and filtering

​Updating, cancelling, and deleting

​Linking a real measurement to a plan

​Permissions

​project_id

​Next steps

Lab view

Measurements

When to use it

Lifecycle

Fields

Requesting a measurement

Scheduling onto a channel

Listing and filtering

Updating, cancelling, and deleting

Linking a real measurement to a plan

Permissions

`project_id`

Next steps