Skip to content
EN
Get API key
Browse documentation

Guides

Recover an agent integration

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 haveUse
CLI runIdThe 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 IDOpenClaw 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.

Select the existing task · this terminal
# 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
Local inspection · no API calls
: "${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-interactive

Choose the recovery action

Read data.status, data.remoteId and data.errorCode in the run record.

Recorded statusWhat to do
succeededCheck access, then export the saved result in step 3.
acceptedCheck access, then recover the accepted job in step 3.
uncertain / intentKeep the task paused. Check remoteId, candidateRemoteIds and History before deciding whether to submit anything again.
failedFix errorCode first. A failed record is retained; a replacement is a new task and can use credits.
partialKeep available outputs. Recover known jobs; for bulk work, inspect each row before replacing failed items.
run_not_foundCheck 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.

Verify access and read the balance
: "${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-interactive

Check 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 fieldExpected
data.accessVerifiedtrue; otherwise fix access before reading results.
data.identity.identity.accountIdThe account that submitted the task.
data.identity.permittedSourcesIncludes the source used by the saved task.
data.identity.identity.recurringAllowedtrue 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.

SituationAction
Wrong accountCheck the environment-key override, selected profile and management/data origins. Restore the intended account before recovery.
Key rotatedUse a replacement key for the same account with the required source permission. Keep the original profile, state directory and run ID.
Claimed trialThe 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.

Finish the existing handoff
: "${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-interactive

3. 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.

Export the saved result
: "${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-interactive

Confirm recovery before resuming

  1. Check exit code 0 and ok: true, then open recovered.json. Saved-result exports have cached: true; usage refers to the original execution.
  2. 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.
  3. 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.

Paste into 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.

get_job
{
  "name": "get_job",
  "arguments": {
    "job_id": "job_REPLACE_WITH_SAVED_ID"
  }
}

Check the MCP job status

ResponseNext action
job.status: pending / processingWait, then read the same job ID. A local timeout does not cancel it.
job.status: completedSave output. Its usage belongs to the original query; get_job does not submit or charge for a new query.
job.status: failed / isError: trueRead the error before using any output. Do not rerun the source automatically.
code: result_unavailableRetry 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.

  1. Append each chunk in order, using next_offset until it is null. Parse the combined JSON only after the last chunk.
  2. 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.
  3. 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.
get_result
{
  "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

SignalFix
400 / 422Check the arguments against the tool or endpoint schema. For CLI requests, use query --dry-run before any new task.
401 / 403For 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.
402Stop new work until the owner resolves funding.
406Use Accept: application/json. For supported content endpoints, request Markdown with X-Respond-With: markdown.
429Honor Retry-After and recover any known job before submitting again. Waiting does not clear a failed CLI run record.
Timeout / 5xx / lost responseRecover known accepted jobs. Keep unknown submission outcomes paused and check History.
run_id_input_conflictRestore the original input. New input needs a deliberate new task and run ID.
run_account_mismatchUse the account-change checklist in step 2; a new run ID is not a recovery shortcut.
output_existsChoose a new output filename. Keep the saved run.
result_unavailableFor 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.

Select diagnostic fields · local only
# Read a saved CLI error envelope; no network request.
jq '{ok, runId, error: (.error | {
  code, httpStatus, retryAfter, runId, remoteId
})}' error.json