Operations
Fleet evidence retention and recovery
Understand when robot location samples, completed work-order detail, and processed geofence projection rows expire without losing trusted current state or audit history.
On this page
Start here
Set bounded workspace evidence windows and know which current and historical records remain after an hourly cleanup. Use readiness and the audit link when investigating a gap in recent detail.
Before you begin
- A signed-in owner or admin to edit Workspace settings → Data retention & export controls
- A selected workspace and the robot or work-order ID you are investigating
Put it into practice
-
Choose the evidence windows
Set location_retention_days (90 by default) and work_order_evidence_retention_days (400 by default). The workspace form accepts whole days from 1 to 36,500 and rejects over-cap input. Raw settings API writes are normalized at use: nonpositive values or values that are not whole numbers of days (including positive fractions) fall back to each default; positive whole values above 36,500 clamp to 36,500 rather than defaulting. These fleet sweeps run whether trace/eval auto_purge_enabled is on or off.
-
Read current state separately
A location page contains append-only samples plus the trusted current position and active geofence state. Expiring an old sample does not clear the robot's current fix, boundary transition_version, active alert, or diagnostic rollup. Heartbeat locations are accepted only within five minutes past or 30 seconds future; the telemetry batch seven-day backlog is a different contract.
-
Follow lifecycle history
For a terminal work order, detail becomes eligible only after both the order's final updated_at and the event's inserted_at cross the configured window. The recent /events response includes archived_audit_url; follow that signed-cursor, workspace/order-bound page for immutable transition history in exact original event time and ID order. The order itself keeps outcome, parts, completion actor, prediction and alert links.
Old high-volume evidence is removed on the rollups queue in workspace jobs capped at 1,000 rows per each of seven datasets (7,000 maximum deletes per job); a scan schedules at most ten workspaces and fair continuations drain remaining backlog. General trace/eval/login/webhook retention remains on default. Trusted current position, geofence safety state, terminal work-order summary, diagnostic trends, and audit history remain discoverable.
01 Effective windows
reference| Evidence | Default | Preserved |
|---|---|---|
| Robot location samples (observed_at) | 90 days, workspace configurable | Robot trusted current position and geofence boundary state |
| Terminal work-order event detail | 400 days, workspace configurable | Order summary, parts/outcome/actor/links and immutable audit history |
| Processed geofence projection outbox | 14 days, fixed | Unprocessed intents, geofence state, active alerts and stable event IDs in projected deliveries |
| Raw robot diagnostics | 30 days, deployment configurable | Minimum 90 days until the historical rollup backfill is confirmed |
| Minute diagnostic rollups | 90 days, fixed | Hour rollups remain for longer trends |
| Hour diagnostic rollups | 400 days, fixed | Year-over-year trend evidence |
| Telemetry batch idempotency ledger | 90 days, fixed | A batch ID older than this may be accepted again |
| Audit events | No automatic time purge | Available until an explicit deletion flow removes them |
02 Find archived order transitions
example# In an authenticated operator browser session, GET the recent detail:
/api/v1/operator/maintenance-work-orders/ORDER_UUID/events
# Follow archived_audit_url from that response, then its next_cursor.
# Audit metadata carries work_order_event_id and event_occurred_at.
Troubleshooting
- A page cursor no longer finds an old sample
- Retention can run between pages. Rehydrate from the first page and current state; never use an old location sample as a durable safety baseline.
- Geofence notifications appear delayed
- A separate fleet-queue recovery job revisits unprocessed outbox rows after 15 minutes when no active or recent delivery job exists. Processed outbox rows expire after 14 days. Webhook projection is fenced by stable event IDs; realtime PubSub delivery can repeat or arrive out of order. Check /ready and fleet/rollups queues before assuming the robot changed boundary state.