Browse documentation
Guides
Recover an interrupted CLI or MCP task using its saved run, job or result ID.
On this page
Start with the ID you saved
Pause the failing task or schedule. Find its receipt in your task folder or agent history, then follow the matching path. These IDs are not interchangeable.
| You have | Use |
|---|---|
| CLI runId | The CLI steps below, with the original profile and state directory. |
| MCP job ID · job_… | get_job on the existing MCP connection. |
| MCP result ID · result_… | get_result to finish reading a large response. |
| OpenClaw run ID | OpenClaw run history, then the FlashData ID recorded by that run. |
1. Inspect the CLI run
Open Bash (Git Bash on Windows) as the original OS user, in your task's output folder. Replace all three values below with those from the original task. Keep this terminal open for steps 2 and 3. Unsetting FLASHDATA_API_KEY lets the CLI use the key saved in this profile.
# Replace these with the values used by the original task.
export FLASHDATA_PROFILE='research'
export FLASHDATA_STATE_DIR='/absolute/path/to/existing/flashdata-state'
export RUN_ID='scheduled-research:2026-11-04:Asia-Shanghai'
unset FLASHDATA_API_KEY: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
: "${RUN_ID:?Set the run ID from the original receipt}"
flashdata doctor --offline --profile "${FLASHDATA_PROFILE:-research}" \
--state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive
flashdata runs show "$RUN_ID" --profile "${FLASHDATA_PROFILE:-research}" \
--state-dir "$FLASHDATA_STATE_DIR" --json --non-interactiveChoose the recovery action
Read data.status, data.remoteId and data.errorCode in the run record.
| Recorded status | What to do |
|---|---|
| succeeded | Check access, then export the saved result in step 3. |
| accepted | Check access, then recover the accepted job in step 3. |
| uncertain / intent | Keep the task paused. Check remoteId, candidateRemoteIds and History before deciding whether to submit anything again. |
| failed | Fix errorCode first. A failed record is retained; a replacement is a new task and can use credits. |
| partial | Keep available outputs. Recover known jobs; for bulk work, inspect each row before replacing failed items. |
| run_not_found | Check the profile, OS user and state directory. Look for saved receipts or History if the journal is lost. |
2. Check CLI account access
These free checks require access to the original account and API origins. Resolve any authentication error before recovering results.
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
flashdata auth status --profile "${FLASHDATA_PROFILE:-research}" \
--state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive
flashdata account balance --profile "${FLASHDATA_PROFILE:-research}" \
--state-dir "$FLASHDATA_STATE_DIR" --json --non-interactiveCheck these fields
A zero balance is a funding issue for new work. It does not by itself mean that the key is invalid.
| auth status field | Expected |
|---|---|
| data.accessVerified | true; otherwise fix access before reading results. |
| data.identity.identity.accountId | The account that submitted the task. |
| data.identity.permittedSources | Includes the source used by the saved task. |
| data.identity.identity.recurringAllowed | true before resuming a recurring task. |
The account changed, or I just claimed a trial
run_account_mismatch means the saved run belongs to a different account or API origin. Reusing the profile name does not transfer that run.
| Situation | Action |
|---|---|
| Wrong account | Check the environment-key override, selected profile and management/data origins. Restore the intended account before recovery. |
| Key rotated | Use a replacement key for the same account with the required source permission. Keep the original profile, state directory and run ID. |
| Claimed trial | The owner account differs from the temporary account. Read trial outputs you already exported. Use a new run ID only for an intended new owner task; it uses the owner's balance. |
Resume an interrupted claim
For an approved claim, run auth finish in its original profile within the 24-hour handoff window. It saves and verifies the owner key, then acknowledges installation. The second command checks the saved access in a new process.
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
# Resume an already approved claim in its original profile.
flashdata auth finish --profile "${FLASHDATA_PROFILE:-research}" \
--state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive
# A second process checks the saved owner access.
flashdata auth status --profile "${FLASHDATA_PROFILE:-research}" \
--state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive3. Recover the CLI result
Choose the saved status from step 1. Use an output filename that does not exist. Both commands verify access and keep the original run; neither submits a replacement query.
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
: "${RUN_ID:?Set the run ID from the original receipt}"
flashdata runs show "$RUN_ID" --result --output recovered.json \
--profile "${FLASHDATA_PROFILE:-research}" --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactiveA polling timeout stops local waiting. Run this recovery command again to keep waiting for the same job.
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
: "${RUN_ID:?Set the run ID from the original receipt}"
flashdata runs recover "$RUN_ID" --output recovered.json --timeout 10m \
--profile "${FLASHDATA_PROFILE:-research}" --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactiveConfirm recovery before resuming
- Check exit code 0 and ok: true, then open recovered.json. Saved-result exports have cached: true; usage refers to the original execution.
- Keep the same account, profile, state and run ID when retrying this occurrence. Do not delete its journal or rename the run to force a retry.
- Resume scheduling only after access and the result are verified. Give each new scheduled occurrence its own run ID.
Recover an MCP task
MCP calls do not create CLI run records. Use the existing MCP connection for the account that submitted the job. Replace the job ID in this prompt and send it to your connected agent.
Recover my existing FlashData job: job_REPLACE_WITH_SAVED_ID.
Use the current MCP connection. Call get_balance with {} to check access,
then get_job with this job_id.
If the reply contains result_id, finish reading its get_result chunks
and combine them before parsing the JSON.
For job.status pending or processing, poll the same job every 5 seconds
for up to 2 minutes, then report the latest status and stop.
For completed, save output and its source URLs and usage in this task.
On an access error, failed job or unavailable result, stop and report the ID.
Do not run a source tool, submit a batch, or create new credentials.Read the original job
For a custom MCP client, pass this object to callTool after replacing job_id. This is a tool call, not a shell command. get_job checks the job account and source permission; a successful get_balance check alone does not prove access to this job.
{
"name": "get_job",
"arguments": {
"job_id": "job_REPLACE_WITH_SAVED_ID"
}
}Check the MCP job status
| Response | Next action |
|---|---|
| job.status: pending / processing | Wait, then read the same job ID. A local timeout does not cancel it. |
| job.status: completed | Save output. Its usage belongs to the original query; get_job does not submit or charge for a new query. |
| job.status: failed / isError: true | Read the error before using any output. Do not rerun the source automatically. |
| code: result_unavailable | Retry the read for a transient delivery failure. If the saved result expired, use earlier exports. Async JSON results are retained for 24 hours. |
A large MCP response was interrupted
Use the saved result_id with the same API key. Start at offset 0 to rebuild the whole response; if you kept the earlier chunks, use their exact next_offset instead. Replace the placeholder before calling this tool.
- Append each chunk in order, using next_offset until it is null. Parse the combined JSON only after the last chunk.
- The cache lasts 10 minutes and keeps the four newest large responses per key. If it expired or was evicted and you saved a job ID, call get_job again and read its new chunks.
- A realtime response has no guaranteed recoverable background job. Without a saved job ID or export, check History and ask before running a new paid query.
{
"name": "get_result",
"arguments": {
"result_id": "REPLACE_WITH_RESULT_ID",
"offset": 0
}
}I have no run or job ID
Check the task's saved files, agent tool history and the owner's request History. A request_id is a diagnostic ID, not a job_id. If you cannot confirm whether the submission was accepted, keep the task paused. Repeating the original source call can create another charge.
Find a fix by error code
| Signal | Fix |
|---|---|
| 400 / 422 | Check the arguments against the tool or endpoint schema. For CLI requests, use query --dry-run before any new task. |
| 401 / 403 | For CLI, check access in step 2. For MCP OAuth, let the host refresh; a revoked grant needs owner-approved reconnection. With an API key, check the host's secret and source permissions. |
| 402 | Stop new work until the owner resolves funding. |
| 406 | Use Accept: application/json. For supported content endpoints, request Markdown with X-Respond-With: markdown. |
| 429 | Honor Retry-After and recover any known job before submitting again. Waiting does not clear a failed CLI run record. |
| Timeout / 5xx / lost response | Recover known accepted jobs. Keep unknown submission outcomes paused and check History. |
| run_id_input_conflict | Restore the original input. New input needs a deliberate new task and run ID. |
| run_account_mismatch | Use the account-change checklist in step 2; a new run ID is not a recovery shortcut. |
| output_exists | Choose a new output filename. Keep the saved run. |
| result_unavailable | For MCP, check the job or chunk steps above. For CLI, recover the accepted remote job. Expired results need an earlier export or your own storage. |
Send a diagnostic to support
For CLI, run this jq filter on the error.json saved by your task. For MCP, copy code, http_status and request_id from the tool response, plus the saved job_id or result_id. Include the client version, endpoint, UTC time and whether acceptance is confirmed or unknown. Exclude credentials, cookies and signed URLs.
# Read a saved CLI error envelope; no network request.
jq '{ok, runId, error: (.error | {
code, httpStatus, retryAfter, runId, remoteId
})}' error.json