Fleet
Bulk fleet operations
Apply one supported action to a reviewed robot selection and follow each target to success or failure. Batches run asynchronously, preserve partial results, and record creation, completion, retry, and cancellation for audit.
On this page
Start here
Bulk operations apply one change to a reviewed fleet selection and preserve a result per target. Creation captures the target set, a worker processes robots independently, and operators watch asynchronous progress.
Before you begin
- Workspace operator access to the batch-operation endpoints
- Verified robot IDs or one filter, plus valid parameters and a partial-failure plan
Put it into practice
-
Preview the target set
Apply cohort, tag, status, model, or other supported fleet filters and verify the same selection in the fleet view. Keep it below the 5,000-target ceiling.
-
Create one batch
Choose explicit IDs or a filter, select the operation kind, and submit its parameters. Record the returned batch ID for status, targets, and audit correlation.
-
Monitor and resolve exceptions
Follow progress events or poll the batch. Inspect each failed target, retry only supported failures after correcting the cause, and cancel queued work when the original intent is no longer safe.
The batch reaches a terminal status, completed and failed target counts reconcile with the captured selection, and audit history shows who created, retried, completed, or cancelled the operation.
01 Operation kinds
reference| kind | params | Notes |
|---|---|---|
| set_status | {"status": "online"} | One of online, offline, charging, error, maintenance. pending and decommissioned are not settable. |
| apply_tags | {"tags": ["night-shift"]} | 1 to 32 tags, normalized before writing |
| remove_tags | {"tags": ["night-shift"]} | 1 to 32 tags |
| add_to_cohort | {"cohort_id": "uuid"} | Cohort must belong to the workspace |
| remove_from_cohort | {"cohort_id": "uuid"} | Cohort must belong to the workspace |
| dispatch_command | {"command_type": "reboot", "payload": {}} | command_type is 2-120 characters; payload must encode to at most 16,000 bytes |
| acknowledge_alerts | none | Acknowledges each target's active fleet alerts |
02 Selecting targets
detailsExplicit ids or a filter, never both
Supply robot_ids (a list) or filter (a map). If both are present robot_ids wins. Ids outside the workspace and decommissioned robots are dropped from an explicit selection; if that leaves nothing the request fails with empty_selection.
Filter keys
query, status, robot_type, cohort_id, and tag -- the same keys the fleet board puts in its URL. An empty filter selects every in-service robot.
5,000 target ceiling
Both selection modes are capped at 5,000 targets; a wider selection is rejected with selection_too_large rather than partially executed. The filter is snapshotted into filter_snapshot at creation, so the target list is fixed at submit time and does not drift as robots change.
03 Create a batch by filter
examplePOST /api/v1/operator/batch_operations
{
"batch_operation": {
"kind": "apply_tags",
"params": {"tags": ["night-shift"]},
"filter": {"cohort_id": "9c1e...", "status": "online"},
"reason": "Rolling out the night shift schedule"
}
}
Response 201:
{
"id": "...", "kind": "apply_tags", "status": "queued",
"selection_mode": "filter",
"filter_snapshot": {"cohort_id": "9c1e...", "status": "online"},
"total_count": 128, "succeeded_count": 0, "failed_count": 0, "skipped_count": 0,
"progress": {"queued": 128, "running": 0, "succeeded": 0, "failed": 0, "skipped": 0},
"targets": [{"id": "...", "target_type": "robot", "target_id": "...", "status": "queued",
"attempts": 0}]
}04 Endpoints
reference| Method and path | Purpose | Success |
|---|---|---|
| GET /api/v1/operator/batch_operations | List batches. Filters: status, kind, limit. Rows omit progress and targets. | 200 |
| POST /api/v1/operator/batch_operations | Create a batch | 201 |
| GET /api/v1/operator/batch_operations/:id | Batch with progress and targets. Filters: target_status, target_limit. | 200 |
| POST /api/v1/operator/batch_operations/:id/cancel | Cancel a queued or running batch | 200 |
| POST /api/v1/operator/batch_operations/:id/retry_failed | Create a child batch over this batch's failed targets | 201 |
05 Status model
detailsBatch status
queued, running, completed, completed_with_errors, cancelled. Only queued and running batches can be cancelled; cancelling marks unprocessed targets skipped with skip_reason batch_cancelled, lets in-flight targets finish, and records who cancelled it.
Target status
queued, running, succeeded, failed, skipped. Each target carries attempts, finished_at, an error string truncated to 500 characters, and a skip_reason such as target_missing, robot_decommissioned, already_in_status, already_in_cohort, not_in_cohort, cohort_missing, no_active_alerts, or batch_cancelled.
06 Progress, retry, and audit
detailsLive progress
Targets are processed in chunks of 25 on the dedicated fleet queue. One target's failure never aborts the batch. Progress is recomputed from the target rows, so the five counts always reconcile with the per-target detail, and fleet.batch_operation.created, .progress, and .completed events stream the same numbers to the console.
Retrying
retry_failed creates a child batch referencing the parent through parent_id and covering only the failed targets, itself bounded by the 5,000 ceiling. A single target can also be retried from its detail view.
Audit
Creation, completion, and cancellation each write a gateway audit event recording the actor, the kind, the target count, and the optional reason supplied in the confirm dialog.
07 Rejections
reference| Status | detail | When |
|---|---|---|
| 400 | invalid_kind | Unknown operation kind |
| 400 | invalid_status / invalid_tags / invalid_cohort | Bad params for the kind |
| 400 | invalid_command_type / invalid_payload | dispatch_command params out of bounds |
| 400 | empty_selection | Neither robot_ids nor filter, or nothing selectable |
| 400 | selection_too_large | More than 5,000 targets |
| 400 | not_cancellable | The batch already finished |
| 400 | no_failed_targets | Nothing to retry |
| 404 | Resource not found | Unknown batch id |
Troubleshooting
- Creation is rejected
- Check for mutually exclusive IDs and filters, an empty selection, unsupported filter keys, invalid kind parameters, or more than 5,000 targets.
- The batch completes with failures
- A target failure does not roll back successful robots. Inspect target-level errors and retry only after the underlying state or parameters are corrected.
- Live progress was missed
- Realtime updates are convenient, not the sole record. Fetch the batch and its paginated targets to reconstruct authoritative progress.