Platform / Fleet

Bulk fleet operations

A batch operation applies one action to many robots, selected explicitly or by filter, and records what happened to each target. Batches run on a dedicated queue, survive individual target failures, and are audited on creation, completion, and cancellation.

API docs

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

details

Explicit 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

example

json

POST /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

details

Batch 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

details

Live 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

Related docs