Browse documentation
Guides
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.
| Use | For | State to preserve |
|---|---|---|
| CLI | An agent with terminal access, cron, or a scheduled script. | The CLI profile, state directory and original run ID. |
| MCP | An 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.
# 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_KEYset -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-interactiveRun this in a fresh scheduled session. Let the host reuse and refresh its approved OAuth credentials. It must be able to reach FlashData without an interactive login at each run.
Reuse the existing FlashData MCP connection in this scheduled environment.
Call get_balance with {}.
Call get_pricing with {"source":"google_search","request_count":1}.
Report the balance and estimated price. Do not search or create new access.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.
mkdir -p flashdata-research
cd flashdata-research{
"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.
#!/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.
# 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-04Confirm 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.
jq '{ok, runId, cached, usage}' runs/2026-11-04/receipt.json
jq '.results[0].organic | map({title, link})' runs/2026-11-04/result.json{
"schemaVersion": 1,
"ok": true,
"runId": "scheduled-research:2026-11-04:Asia-Shanghai",
"cached": true
}Keep the files between runs
| File | Use |
|---|---|
| runs/DATE/request.json | Exact input for that occurrence; changing it makes the runner stop. |
| runs/DATE/result.json + receipt.json | The 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_DIR | Protected 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.
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.
{
"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.
| Setting | Use |
|---|---|
| Concurrency | One active execution for this workflow, with durable state. |
| Runtime | Use 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. |
| Retries | Keep the original occurrence and scheduled date, including after midnight. A manual test uses its invocation date in Asia/Shanghai. |
| Missed occurrences | Choose whether to skip or catch up. A search run today returns current data, even if labeled with yesterday's date. |
| Delivery | Save 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.
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.
: "${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.
: "${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
)cat openclaw-test-run.jsonInspect 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.
: "${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" --json3. 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.
: "${OPENCLAW_JOB_ID:?Set the saved OpenClaw job ID}"
openclaw automations show "$OPENCLAW_JOB_ID" --json
openclaw automations runs "$OPENCLAW_JOB_ID" --limit 5 --jsonopenclaw automations enable "$OPENCLAW_JOB_ID"openclaw automations disable "$OPENCLAW_JOB_ID"Set cost and failure rules
| Situation | Action |
|---|---|
| Cost planning | Price per query × planned occurrences. Add model and host costs separately; result count is not query count. |
| Shared account balance | Enforce your budget in the scheduler or host. These examples do not impose a separate key spending cap. |
| 401 / 403 / 402 | Pause future dispatches. Fix credentials, permission or balance; resume with the original occurrence and saved state. |
| 429 | Respect Retry-After. Inspect the CLI run or MCP occurrence before deciding whether a new submission is safe. |
| Unknown submission outcome | Keep 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
- Pause the scheduler to stop future invocations.
- Revoke the agent connection, OAuth app or API key in the console. Revocation blocks new authenticated use; it does not erase exported files.
- 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.