Skip to content
EN
Get API key
Browse documentation

Get started

Automate with the FlashData CLI

Validate a request, run it from a script and read separate result and error receipts.

On this page

1. Select the existing profile

Use the installed CLI, Bash and jq. On Windows, run the shell examples in Git Bash. This walkthrough uses an authenticated research profile; set FLASHDATA_STATE_DIR to the absolute directory where that profile is stored.

Use the same OS user and state directory on every command. FLASHDATA_API_KEY overrides the saved key; leave it unset to use the profile. The CLI does not load .env files.

Check saved access
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
flashdata auth status --profile research --state-dir "$FLASHDATA_STATE_DIR" --json

Default state locations

Use your original --state-dir if you chose a custom location. auth status should report data.accessVerified: true. For an unattended deployment, import the owner key through stdin from its secret store.

OSDirectory
Windows%APPDATA%/FlashData
macOS~/Library/Application Support/FlashData
Linux$XDG_STATE_HOME/flashdata or ~/.local/state/flashdata

2. Validate the request and price

Save request.json, then run the free checks in the same directory. The filter prints true only when a source price is available and the balance covers one query. Stop on a nonzero exit. A price check does not reserve credits.

request.json
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  }
}
Bash + jq · no paid submission
set -euo pipefail
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
flashdata account balance --profile research --state-dir "$FLASHDATA_STATE_DIR" \
  --json --non-interactive > balance.json
flashdata query --input request.json --dry-run --run-id cli-research-001 \
  --profile research --state-dir "$FLASHDATA_STATE_DIR" \
  --json --non-interactive > preflight.json
jq -e --slurpfile balance balance.json '
  .ok and .data.dryRun and .data.estimateAvailable
  and ($balance[0].ok == true)
  and any(.data.estimate.prices[]?;
    .source == "google_search" and .available == true
    and (.estimatedCredits | type == "number")
    and ($balance[0].data.availableCredits | type == "number")
    and .estimatedCredits <= $balance[0].data.availableCredits)
' preflight.json

3. Run and read the receipt

After the checks pass, save run-search.sh and run bash run-search.sh. The first successful execution submits one search. Each attempt saves its files in a new cli-run directory; the stable run ID lets the CLI reuse an earlier success for the same account, profile and state directory.

run-search.sh
#!/usr/bin/env bash
set -euo pipefail
umask 077
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
dir=$(mktemp -d "cli-run.XXXXXX")
if ! flashdata query --input request.json --run-id cli-research-001 \
  --profile research --state-dir "$FLASHDATA_STATE_DIR" \
  --output "$dir/result.json" --timeout 2m --json --non-interactive \
  > "$dir/receipt.json" 2> "$dir/error.json"; then
  cat "$dir/error.json" >&2
  printf 'Inspect saved run cli-research-001; receipts: %s\n' "$dir" >&2
  exit 1
fi
jq -e '.schemaVersion == 1 and .ok == true' "$dir/receipt.json" >/dev/null
jq -e '.status == "done" and .source == "google_search"' "$dir/result.json" >/dev/null
jq -r '.results[]?.organic[]? | [.title, .link] | @tsv' "$dir/result.json"
jq '{runId, cached, usage}' "$dir/receipt.json"
printf 'Files: %s\n' "$dir"

Know which file to read

The CLI envelope and the source response are different JSON documents. Without --output, the source response is in data. This example uses --output, so read source fields from the saved result.json.

FileRead
receipt.jsonok, runId, cached, usage and the output path. A cached receipt reports the original usage, not a new charge.
result.jsonsource, status, results and usage. For Google Search, read results[].organic[]. An empty array can be a valid search result.
error.jsonOn nonzero exit, inspect error.code, error.httpStatus, error.retryAfter and any run/job IDs.
receipt.json · illustrative excerpt
{
  "schemaVersion": 1,
  "ok": true,
  "runId": "cli-research-001",
  "cached": false,
  "data": {
    "output": "cli-run.EXAMPLE/result.json"
  },
  "usage": {
    "credits": 0.02
  }
}

Recover without another search

Inspect the saved run before retrying. With access to the original account, export a successful run to a filename that does not exist yet. Claiming switches from the trial account to the owner; keep previously exported trial results and use new IDs for new owner tasks. A changed request under the same run ID is rejected; use a new ID only for an intentional new task.

Inspect, then export a saved success
flashdata runs show cli-research-001 --profile research \
  --state-dir "$FLASHDATA_STATE_DIR" --json
flashdata runs show cli-research-001 --result --output recovered.json \
  --profile research --state-dir "$FLASHDATA_STATE_DIR" --json

Add scheduling when the script works

Use --recurring with installed owner access, one stable ID per scheduled occurrence and persistent state. A trial cannot run recurring work. Your host owns the schedule; the flag only checks access. Use the complete recurring-task runner for scheduled-date handling and restarts.

Optional: private download storage

For youtube download --storage-config storage.json, save only this storage object as storage.json and replace placeholders locally. The file must be private and owned by the executing user. Use the matching permission command before running a download.

storage.json · S3
{
  "storage_type": "s3",
  "storage_url": "YOUR_BUCKET",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "region": "us-east-1"
}
Restrict file access
chmod 600 storage.json

Related guides