Skip to content
EN
Get API key
Browse documentation

Guides

Run recurring agent tasks

Reuse approved access, run one search per scheduled occurrence, and recover without accidentally submitting the same work again.

On this page

Choose how the task runs

Your agent host or OS scheduler supplies the timing. FlashData supplies the data. Choose one execution path and test it in the environment that will run unattended.

UseForState to preserve
CLIAn agent with terminal access, cron, or a scheduled script.The CLI profile, state directory and original run ID.
MCPAn agent host with a connected FlashData server.The host's credentials, occurrence record, job IDs and results.

Check access in the scheduled environment

Reuse an existing owner connection with google_search permission. Claim temporary access before recurring use. Test from a fresh scheduled process or session, not only an interactive one.

Use Bash and jq (Git Bash on Windows), under the OS user that saved the key. Set your existing profile name and absolute state directory below. Run both blocks in the same terminal; the runner reuses these settings.

The access check must print true. Compare availableCredits with estimatedCredits before the first search. These checks do not submit a query.

Set your saved connection
# Use the profile and state directory that already hold your owner key.
export FLASHDATA_PROFILE='research'
export FLASHDATA_STATE_DIR='/absolute/path/to/existing/flashdata-state'
export FLASHDATA_BIN="$(command -v flashdata)"
unset FLASHDATA_API_KEY
Free access, balance and price checks
set -euo pipefail
export FLASHDATA_BIN="${FLASHDATA_BIN:-$(command -v flashdata)}"
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
: "${FLASHDATA_BIN:?Set the absolute path to the FlashData executable}"
profile=${FLASHDATA_PROFILE:-research}
test -d "$FLASHDATA_STATE_DIR" || { echo 'Existing state directory not found.' >&2; exit 1; }
"$FLASHDATA_BIN" --version
jq --version
"$FLASHDATA_BIN" auth status --profile "$profile" \
  --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive |
  jq -e '.ok and .data.accessVerified
    and (.data.identity.identity.recurringAllowed == true)
    and (.data.identity.permittedSources | index("google_search") != null)'
"$FLASHDATA_BIN" account balance --profile "$profile" \
  --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive
"$FLASHDATA_BIN" account pricing --source google_search --request-count 1 \
  --profile "$profile" --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive

CLI: save one task per occurrence

Create the task folder below, then save request.json and run-research.sh inside it. Keep this folder separate from the existing credential state directory. One date represents one Google query; num sets the number of results. Give a different workflow its own run-ID prefix before its first execution.

Create the task folder
mkdir -p flashdata-research
cd flashdata-research
request.json
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  }
}

Save run-research.sh

Create run-research.sh beside request.json in the task folder. Copy the complete script below into it and save it before running or scheduling the task.

The script freezes the input for each date and keeps a receipt, result and error file for each attempt. Only successful attempts publish result.json and receipt.json at the dated folder's top level. --recurring checks owner access; it does not create a schedule.

run-research.sh
#!/usr/bin/env bash
set -euo pipefail
umask 077
slot=${1:?Pass the scheduled date as YYYY-MM-DD}
[[ "$slot" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ ]] || exit 2
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
: "${FLASHDATA_BIN:?Set the absolute path to the FlashData executable}"
profile=${FLASHDATA_PROFILE:-research}
cd -- "$(dirname -- "$0")"
dir="runs/$slot"
mkdir -p "$dir"
if [[ -e "$dir/request.json" ]]; then
  cmp -s request.json "$dir/request.json" || {
    echo 'Input changed for this slot. Inspect its saved run.' >&2; exit 1;
  }
else
  (set -C; cat request.json > "$dir/request.json")
fi
attempt=$(mktemp -d "$dir/attempt.XXXXXX")
if ! "$FLASHDATA_BIN" query --input "$dir/request.json" --recurring \
  --run-id "scheduled-research:$slot:Asia-Shanghai" \
  --profile "$profile" --state-dir "$FLASHDATA_STATE_DIR" \
  --output "$attempt/result.json" --timeout 2m --json --non-interactive \
  > "$attempt/receipt.json" 2> "$attempt/error.json"; then
  cat "$attempt/error.json" >&2
  exit 1
fi
jq -e '.ok == true' "$attempt/receipt.json" >/dev/null
jq -e '.source == "google_search" and .status == "done"
  and (.results[0].organic | type == "array")' "$attempt/result.json" >/dev/null
# Publish a stable path only after the query and its receipt both succeed.
cp "$attempt/result.json" "$dir/result.next.json"
mv "$dir/result.next.json" "$dir/result.json"
cp "$attempt/receipt.json" "$dir/receipt.next.json"
mv "$dir/receipt.next.json" "$dir/receipt.json"
jq '{runId, cached, usage}' "$attempt/receipt.json"
printf 'Saved result: %s\n' "$dir/result.json"

Run once, then test a fresh-process retry

Run from the task folder. The first command submits a search. The second uses the same account, input, profile and state to read the saved result after checking that access is still valid.

One occurrence · two process starts
# Use the date of the intended occurrence, including on retries.
bash run-research.sh 2026-11-04

# Same account, input, profile and state: reuse the completed run.
bash run-research.sh 2026-11-04

Confirm the result was reused

The second receipt should show cached: true. Its usage belongs to the original search. An empty organic array can still be a successful result.

Inspect the saved result and receipt
jq '{ok, runId, cached, usage}' runs/2026-11-04/receipt.json
jq '.results[0].organic | map({title, link})' runs/2026-11-04/result.json
Second receipt · excerpt
{
  "schemaVersion": 1,
  "ok": true,
  "runId": "scheduled-research:2026-11-04:Asia-Shanghai",
  "cached": true
}

Keep the files between runs

FileUse
runs/DATE/request.jsonExact input for that occurrence; changing it makes the runner stop.
runs/DATE/result.json + receipt.jsonThe last successful attempt. Only consume them after the current command exits successfully.
runs/DATE/attempt.*/Result, receipt and error for each attempt, including failures.
FLASHDATA_STATE_DIRProtected credentials and CLI run records. Keep the same profile and OS user.

MCP: persist the occurrence and job ID

Use this task body with a host that keeps durable task state and allows one active execution per occurrence. Save the returned job ID immediately; after a restart, read the accepted job instead of searching again.

MCP recurring task · save as recurring-task.txt
Use the scheduler's original occurrence ID and scheduled time.
Reuse the existing FlashData MCP connection and saved occurrence record.
1. If this occurrence is complete, return its saved result without searching.
2. If it has a job ID, call get_job with that job_id to read the existing work.
3. If a submission started but has no result or job ID, stop for review.
4. For a new occurrence, check get_balance and get_pricing for one google_search.
   Continue only within the approved per-task budget and available balance.
5. Persist submission_started before calling google_search once with:
   {"query":"battery recycling pilot plant announcements","num":5,"gl":"us","hl":"en","tbs":"qdr:w","mode":"async"}
6. Save the returned job ID immediately. Read it with get_job until terminal; stop on failure.
   Keep the ID across timeouts and stop waiting at the host's deadline.
7. Save the result, source URLs and usage, then mark this occurrence complete.
On 401, 403, 402, 429 or an unknown outcome, stop and report the saved record.
Honor Retry-After. Do not create replacement access or another paid query.
Keep the report local; use a delivery destination only if separately configured.

What the host must persist

A prompt alone cannot prevent duplicates. MCP calls do not inherit CLI run-ID protection. Your host must persist the original occurrence, submission state and job ID. If it cannot, use the CLI runner for the data step. This example record belongs to your host; it is not an MCP request.

Host record · illustrative
{
  "occurrence": "research:2026-11-04:Asia-Shanghai",
  "state": "accepted",
  "job_id": "<returned job ID>",
  "output": null
}

Schedule the tested task

The example below uses OpenClaw at 09:00 Asia/Shanghai. Create the job disabled, run that saved job manually, inspect its output, then enable it. For another scheduler, follow the same sequence with its test-run controls.

SettingUse
ConcurrencyOne active execution for this workflow, with durable state.
RuntimeUse the same OS user and absolute paths for the CLI, task folder and credential state. Terminal exports are not automatically inherited by a running Gateway.
RetriesKeep the original occurrence and scheduled date, including after midnight. A manual test uses its invocation date in Asia/Shanghai.
Missed occurrencesChoose whether to skip or catch up. A search run today returns current data, even if labeled with yesterday's date.
DeliverySave locally first. Configure a destination and notification policy before sending reports.

CLI task body for an agent host

Replace the profile and path placeholders, then save recurring-task.txt in the task folder. Use this body for CLI execution, or the MCP body above for MCP execution. A direct OS scheduler can run the Bash script with these environment variables without a model.

recurring-task.txt
Run the approved FlashData research task under the OS user that saved the key.
Runner: <absolute path to run-research.sh>
Set these environment variables for the runner process:
FLASHDATA_BIN: <absolute path to flashdata>
FLASHDATA_PROFILE: <existing profile name>
FLASHDATA_STATE_DIR: <existing absolute state directory>
Keep FLASHDATA_API_KEY unset to reuse the saved credential.
Use the original scheduled date in Asia/Shanghai, as YYYY-MM-DD.
For a manual run, save its invocation date before execution.
Run: bash "<absolute path to run-research.sh>" YYYY-MM-DD
Keep that date on retries, even after midnight. Allow one active execution.
Keep the same profile, request.json and state directory.
Only read the dated result.json after the command exits successfully.
Report source links, run ID and usage. Keep outputs local.
On error, stop and report the saved error. Do not start replacement work or create new access.

1. Create a disabled OpenClaw job

Use a running Gateway and an existing agent that passed the access check. The commands below use OpenClaw 2026.10.10; update older clients if --wait is unavailable. In the folder containing recurring-task.txt, set OPENCLAW_AGENT_ID to that agent's ID.

The command saves openclaw-job.json without overwriting an existing file. Read it and set OPENCLAW_JOB_ID to the returned job ID. If creation loses its response, inspect automations list --all --json before creating another job. --no-deliver disables automatic announcement; the task body also keeps reports local.

Bash · creates a disabled job
: "${OPENCLAW_AGENT_ID:?Set the existing OpenClaw agent ID}"
test -s recurring-task.txt || exit 1
# Keep the receipt. An existing file blocks accidental recreation.
(
  set -o noclobber
  openclaw automations add --name flashdata-daily-research \
    --agent "$OPENCLAW_AGENT_ID" \
    --cron "0 9 * * *" --tz Asia/Shanghai --exact \
    --session isolated --disabled --no-deliver \
    --message "$(cat recurring-task.txt)" --json > openclaw-job.json
)

2. Test the saved job before enabling it

Run the saved job once while its schedule stays disabled. Budget for one test search and model costs; a matching completed CLI occurrence can reuse its result. This command waits up to 10 minutes.

Expect completionStatus: succeeded, then check the saved result, source links and usage. For CLI, read runs/DATE/result.json and receipt.json; for MCP, read the host's saved occurrence and job result. enqueued: true alone means accepted, not completed.

Run once · save the test receipt
: "${OPENCLAW_JOB_ID:?Set the saved OpenClaw job ID}"
# Run the saved job once; its schedule stays disabled.
(
  set -o noclobber
  openclaw automations run "$OPENCLAW_JOB_ID" \
    --wait --wait-timeout 10m --json > openclaw-test-run.json
)
Read the test receipt
cat openclaw-test-run.json

Inspect a timed-out or failed test

A timeout stops waiting, not the Gateway task. Read recent history if the receipt is empty. Set OPENCLAW_RUN_ID to the OpenClaw runId from the receipt or history, then inspect that execution. Do not repeat the run command to check progress.

This is the scheduler execution ID, not the FlashData recurring run ID or an MCP data job ID. If the agent could not log in or execute the data task, keep the schedule disabled and repair that step first.

Inspect the same execution
: "${OPENCLAW_JOB_ID:?Set the saved OpenClaw job ID}"
cat openclaw-test-run.json
openclaw automations runs "$OPENCLAW_JOB_ID" --limit 5 --json

# Set this from the receipt or history; this is OpenClaw's run ID.
: "${OPENCLAW_RUN_ID:?Set the OpenClaw test run ID}"
openclaw automations runs "$OPENCLAW_JOB_ID" \
  --run-id "$OPENCLAW_RUN_ID" --json

3. Enable after checking the output

Review the saved agent, schedule, timezone and completed test. Enable only after the output is correct and the recurring cost is approved. Disabling later stops future invocations; it does not cancel an already submitted query.

Review the saved job and test history
: "${OPENCLAW_JOB_ID:?Set the saved OpenClaw job ID}"
openclaw automations show "$OPENCLAW_JOB_ID" --json
openclaw automations runs "$OPENCLAW_JOB_ID" --limit 5 --json
Enable the daily schedule
openclaw automations enable "$OPENCLAW_JOB_ID"
Pause future runs when needed
openclaw automations disable "$OPENCLAW_JOB_ID"

Set cost and failure rules

SituationAction
Cost planningPrice per query × planned occurrences. Add model and host costs separately; result count is not query count.
Shared account balanceEnforce your budget in the scheduler or host. These examples do not impose a separate key spending cap.
401 / 403 / 402Pause future dispatches. Fix credentials, permission or balance; resume with the original occurrence and saved state.
429Respect Retry-After. Inspect the CLI run or MCP occurrence before deciding whether a new submission is safe.
Unknown submission outcomeKeep the saved state and stop. Recover a known job ID; do not create a fresh run ID to bypass the uncertainty.

Stop the schedule and revoke access separately

  1. Pause the scheduler to stop future invocations.
  2. Revoke the agent connection, OAuth app or API key in the console. Revocation blocks new authenticated use; it does not erase exported files.
  3. Repeat the free access check from a fresh process. It should fail after revocation. CLI auth logout only removes local credentials; it does not revoke remote access.