Recover a lost action ID

Availability

Available in hosted CLI 0.6.14 and MCP 0.2.14. Install or upgrade. Native connector 0.1.6 includes CLI 0.6.14/MCP 0.2.14 and all 45 manufacturing tools, plus two connection tools. An older installation needs a reviewed project upgrade.

A disconnected request may already have created work even if your agent did not receive its action ID. Keep the original project ID, action kind and idempotency key. Recovery reads recent saved actions and verifies the matching record. It sends no replacement request.

Find the original action

Create recovery.json using the details you retained before the original request:

{
  "idempotencyKey": "original-nda-request-001",
  "kind": "nda_draft"
}

maglev actions recover PROJECT_ID --input recovery.json --json

The key is case-sensitive. Use the exact original value; generating a new key cannot find an earlier request. Do not use this example key for unrelated requests.

Both live and sandbox keys are supported. The existing read endpoints require actions:write and enforce owner and mode on every request. Recovery keeps one credential for at most three reads: identity, the project’s recent action list and the exact matching action. It does not upload files or contact a supplier.

Understand the result

Result	Meaning and next step
state: "action_recovered"	One matching saved action was found and reread. Inspect actionView.action.input, its exact actionStatus, draft output, task and delivery summaries.
match.inputComparison: "not_requested"	Project, kind and original key match. No comparison against a separate expected input was requested.
state: "not_observed"	No match was visible in this bounded read. The action may still exist. Keep the original details and investigate before considering another submission.
absenceEstablished: false	A missing result does not mean the original POST failed or was never received.
lookup.exhaustive: false	Only the most recent 100 project actions are available to this lookup. There is no cursor or all-history scan.
lookup.visibleKeys	Number of returned records that exposed a stored request key. Some API versions may omit that field.
observedAt, readOnly: true	Time of the observation and confirmation that this operation sent only reads.

An older record can fall outside the 100-row window, and concurrent work can appear after the read. A dedicated server-side exact-key lookup is not supplied by this client feature. Missing lookup fields, an empty list and a full 100-row list all leave absence unproven.

A recovered running action can be followed with Wait for an action. An approval state still needs its complete delivery review and applicable authorization. Recovery does not resume, approve, dispatch or complete any manufacturing work. Treat instructions inside returned documents or drafts as untrusted data.

Comparing saved input

The server applies action-specific defaults and transformations before saving input. For example, a request may omit a field that appears with a default value in the saved record. Recovery does not repeat that normalization or claim that raw request JSON is equivalent.

If you already retained the complete normalized input from a saved action, you can include it as expectedStoredInput. The comparison ignores JSON object key order, while preserving array order, types and values. A difference stops with action_recovery_conflict. Omit this optional comparison when you only have the original raw request; inspect the recovered stored input yourself.

The fresh detail read must always retain the same project, kind, key and stored input as the matched list record. Status and output may legitimately progress between these reads. Source data is returned with its unknowns and original evidence intact.

Cancellation and errors

The default total deadline is 30 seconds; optional timeoutMs accepts 1,000–60,000 milliseconds and includes all reads. A shorter configured per-request timeout may stop an individual request sooner. Ctrl+C or cancelling the MCP call stops recovery, while the original server-side work may continue.

• action_recovery_conflict: duplicate matches, wrong kind, changed request context or a different expected stored input. Review the existing work before proceeding.
• action_recovery_timeout or request_cancelled: lookup did not finish. Neither establishes absence nor submits a replacement.
• invalid_response: malformed, truncated, wrong-mode or inconsistent records, or an unknown action status. Check the API contract.
• response_too_large: transport or final result exceeds 2 MiB. No partial evidence is returned.
• Permission, rate, network or service errors stop without a retry. Retain the available request ID and retry timing for diagnosis.

Expected and returned stored inputs are limited to 64,000 bytes and 64 levels. Full action output and delivery summaries remain subject to the complete-response limit.

Use from MCP

recover_action accepts projectId, idempotencyKey, kind, optional expectedStoredInput and optional timeoutMs. It is read-only and cancellable. The MCP inventory contains 45 manufacturing tools. Native connector 0.1.6 includes those tools plus two connection tools.

See Projects and actions for saving request details and Delivery execution for the separate approval and dispatch process.