Browse documentation
Get started
Check your access, fix a failed request or find an answer about using FlashData.
On this page
Start with a free access check
Run the check where the task failed. Use its existing credentials; these commands do not submit a query.
Use your saved CLI access. For a named profile, append --profile NAME to each command. These reads do not spend query credits.
flashdata --version
flashdata doctor --offline
flashdata auth status --jsonUse the task's existing FLASHDATA_API_KEY in the same terminal, container or scheduled job. Requires cURL 7.76+.
(
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
curl --fail-with-body --silent --show-error --max-time 20 \
--header "X-API-Key: $FLASHDATA_API_KEY" \
'https://api.flashdata.dev/v2/api-access/identity' || exit
printf '\n'
)Use the task's existing FLASHDATA_API_KEY in the same terminal, container or scheduled job.
& {
$ErrorActionPreference = 'Stop'
if ([string]::IsNullOrWhiteSpace($env:FLASHDATA_API_KEY)) {
throw 'Set FLASHDATA_API_KEY first'
}
$flashdataHeaders = @{ 'X-API-Key' = $env:FLASHDATA_API_KEY }
$flashdataBase = 'https://api.flashdata.dev/v2'
$flashdataUri = "$flashdataBase/api-access/identity"
Invoke-RestMethod -Uri $flashdataUri `
-Headers $flashdataHeaders -TimeoutSec 20 -MaximumRedirection 0 |
ConvertTo-Json -Depth 20
}What to check
The identity should have access: ready and include your source in scopes. In CLI JSON, the identity is at data.identity.identity; also require data.accessVerified: true. A successful command with accessVerified: false has not verified access.
For a named CLI profile, append --profile NAME to every command below. Keep the original --state-dir and OS user. FLASHDATA_API_KEY overrides a saved CLI key; SDKs and MCP hosts use their own credential configuration.
Find and fix the problem
Open the symptom that matches your error. Use IDs and receipts from the original task.
Command not found or profile missing
No executable: install the release for your OS/CPU and add its directory to PATH. Missing profile: use the original OS user and state directory. Check inside the scheduler or container, too.
command -v flashdata
flashdata --version
flashdata doctor --offlineGet-Command flashdata
flashdata --version
flashdata doctor --offline401 / 403: key, scope or expiry
To replace a saved owner key, paste the approved key into the hidden prompt. If FLASHDATA_API_KEY is set, update that secret in the runtime instead; saving another CLI key will not override it.
- 401: check for an expired, revoked or incorrectly configured key. 403: compare the requested source with the identity's scopes.
- REST and SDKs use X-API-Key. An MCP OAuth token cannot replace an API key. For temporary access, use the claim recovery below.
flashdata auth login --replace
flashdata auth status --jsonClaim approved, but the agent still has trial access
Finish the handoff in the same CLI profile that created the claim. The owner completes signup, email verification and consent in the browser; the CLI receives the credential.
flashdata auth finish --wait --timeout 10m
flashdata auth status --jsonRequest a fresh link for the existing trial, let the owner approve, then run auth finish. Do not run init again.
flashdata auth claim402: insufficient credits
Compare availableCredits with the current price for your source. Claim an exhausted trial to use the owner's balance, or let the owner review Billing before retrying.
Use your saved CLI access. For a named profile, append --profile NAME to each command. These reads do not spend query credits.
flashdata account balance
flashdata account pricing --source google_search --request-count 1Use the task's existing FLASHDATA_API_KEY in the same terminal, container or scheduled job. Requires cURL 7.76+.
(
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
curl --fail-with-body --silent --show-error --max-time 20 \
--header "X-API-Key: $FLASHDATA_API_KEY" \
'https://api.flashdata.dev/v2/api-access/balance' || exit
printf '\n'
curl --fail-with-body --silent --show-error --max-time 20 \
--header "X-API-Key: $FLASHDATA_API_KEY" \
'https://api.flashdata.dev/v2/api-access/pricing?source=google_search&request_count=1' || exit
printf '\n'
)Use the task's existing FLASHDATA_API_KEY in the same terminal, container or scheduled job.
& {
$ErrorActionPreference = 'Stop'
if ([string]::IsNullOrWhiteSpace($env:FLASHDATA_API_KEY)) {
throw 'Set FLASHDATA_API_KEY first'
}
$flashdataHeaders = @{ 'X-API-Key' = $env:FLASHDATA_API_KEY }
$flashdataBase = 'https://api.flashdata.dev/v2'
$flashdataUri = "$flashdataBase/api-access/balance"
Invoke-RestMethod -Uri $flashdataUri `
-Headers $flashdataHeaders -TimeoutSec 20 -MaximumRedirection 0 |
ConvertTo-Json -Depth 20
$flashdataUri = "$flashdataBase/api-access/pricing?source=google_search&request_count=1"
Invoke-RestMethod -Uri $flashdataUri `
-Headers $flashdataHeaders -TimeoutSec 20 -MaximumRedirection 0 |
ConvertTo-Json -Depth 20
}429: wait before retrying
Read Retry-After on the failed response: seconds or an HTTP date. Wait until then and reduce concurrency. Trial registration allows three registrations per IP per 24-hour window; reuse the original profile and registration proof.
This free read demonstrates saving headers, status and body. Use the Retry-After from the operation that failed; query, registration and account-read limits can differ.
# Bash + cURL + jq. This is a free account read.
(
test -n "$FLASHDATA_API_KEY" || { printf 'Set FLASHDATA_API_KEY first\n' >&2; exit 1; }
curl --silent --show-error --max-time 20 \
--header "X-API-Key: $FLASHDATA_API_KEY" \
--dump-header diagnostic-headers.txt --output diagnostic.json \
--write-out '%{http_code}\n' \
'https://api.flashdata.dev/v2/api-access/identity' > diagnostic-status.txt || exit
printf 'HTTP '; cat diagnostic-status.txt
awk 'tolower($1) == "retry-after:" {
$1=""; sub(/^ /, ""); sub(/\r$/, ""); print "Retry-After: " $0
}' diagnostic-headers.txt
if jq -e 'type == "object"' diagnostic.json >/dev/null 2>&1; then
jq '{access, scopes, status, code, requestId}
| with_entries(select(.value != null))' diagnostic.json
else
printf 'Non-JSON response saved in diagnostic.json; check the HTTP status.\n'
fi
)flashdata account limits400 / 422: rejected input or processing failure
Read code, detail and fieldErrors from the HTTP error. Correct the request body, save it as request.json, then validate it. Keep Download storage credentials in a private input file. If 422 comes from an existing job's result, inspect job.error first.
flashdata query --input request.json --mode async --dry-run --jsonJob pending, or HTTP 200 with a failed job
Read the job from submission.json, your saved async receipt. HTTP 200 means the status read succeeded; job.status is the task outcome (data.status in CLI JSON). For Batch, save the relevant entry from queries as submission.json.
| State or error | Next action |
|---|---|
| pending / processing | Wait on the same job; do not submit it again. |
| completed | Fetch and save the existing result. |
| failed | Inspect job.error before submitting corrected work. |
| 404 | Check the job ID and the submitting account. |
| 409 | Results are not ready. Keep polling the same job. |
| 410 | Stored JSON expired after 24 hours. Use your saved copy; delivered media has its own storage retention. |
# Bash + jq. CLI receipts use remoteId; HTTP receipts use id.
(
set -e
JOB_ID=$(jq -er '.remoteId // .id' submission.json)
flashdata jobs get "$JOB_ID" --json
)flashdata jobs wait JOB_IDflashdata jobs result JOB_ID --output recovered-result.json# Bash + cURL + jq. Read the saved async submission receipt.
(
set -e
test -n "$FLASHDATA_API_KEY" || { printf 'Set FLASHDATA_API_KEY first\n' >&2; exit 1; }
STATUS_URL=$(jq -er '(.submission // .).links[]
| select(.rel == "self") | .href' submission.json)
curl --fail-with-body --silent --show-error --max-time 30 \
--header "X-API-Key: $FLASHDATA_API_KEY" \
--header 'Accept: application/json' \
"$STATUS_URL" --output job.json
jq '.job | {id, status, error}' job.json
)Timeout / 5xx: was the task accepted?
Inspect the original run and History before retrying a POST. Recover a confirmed accepted job. If acceptance is unknown, keep the run ID and contact support; changing IDs and resubmitting can duplicate charges.
flashdata runs show RUN_IDflashdata runs recover RUN_IDCLI output_exists: result file already exists
The CLI does not overwrite --output files. Read the existing file, or choose a new output filename while keeping the original --run-id and request. Do not invent a new run ID to bypass this error.
flashdata runs show RUN_IDEmpty search, missing captions or unreadable download
These commands only read local result files, not the CLI's stdout envelope.
If status is done and organic is empty, loosen query filters. Keep the empty outcome in your task record.
jq '{status, usage, resultCount: (.results | length)}' result.json
jq '(.results[0].organic // []) | length' result.jsonMetadata lists language codes, not whether a track is manual or automatic. Choose a listed language and set auto explicitly: true for automatic, false for manual. No matching track means no captions for that selection; FlashData does not generate a replacement.
jq '.results[0].transcriptLanguages' metadata.jsonRead the completed delivery.json receipt. Download the object with your destination-storage credentials, then compare its size and MD5 with the receipt. A private file_url does not become public after delivery.
jq '.results[0] | {file_url, file_size, md5}' delivery.jsonMCP tools missing or authentication expired
Check the host running the task. A listed server confirms configuration, not a working connection. If the configured hosted OAuth connection requires login, run its login command and complete browser approval, then refresh the tool list.
Open /mcp in the Codex CLI to check connection status and tools. In the app, check the configured server and start a fresh session after setup changes.
codex mcp listcodex mcp login flashdata --scopes mcp:researchopenclaw mcp doctor flashdata --probeopenclaw mcp login flashdata
openclaw mcp doctor flashdata --probeOAuth login does not repair an API-key connection. Check the key in the host's environment and its source permissions. For local stdio, check the MCP package's Node.js requirement and restart the host after updating its environment.
node --versionSkill installed but the agent cannot find or use it
Check the same project, host profile and install location, then start a fresh agent session. CLI task skills need the CLI; flashdata-mcp needs a connected MCP server. Installing a skill does not connect a server or grant account permissions.
flashdata skills verify --agent codexflashdata skills verify --agent codex --skill flashdata-mcpopenclaw skills list --eligible
openclaw skills checkFrequently asked questions
Getting connected
Do I need an AI agent?
No. Use the HTTP API, Go/Python/TypeScript SDK, CLI or console directly. MCP and skills are additional options for agents.
Which interface should I choose?
Use an SDK or HTTP API inside an app, the CLI for terminal tasks, and MCP for an MCP-capable host. Skills provide instructions for either CLI tasks or connected MCP tools; they do not replace authentication.
Can I reuse credentials for recurring tasks?
Yes. Use owner access and preserve the same protected CLI profile, runtime secret or MCP connection. For API-key access, check recurringAllowed: true. Your host or scheduler runs the schedule.
Does deleting local settings revoke access?
No. Revoke the API key or connection in the console. Deleting local settings only removes that local copy.
Trials and credits
Can an agent try FlashData before signup?
Yes, with eligible temporary access through the CLI or onboarding API. Reuse the same profile and registration proof. Continued use needs claiming or an existing owner API key.
Does claiming add another trial grant?
Claiming itself grants no extra trial credits. Future requests use the owner's account balance; unused temporary credits do not transfer. A newly created account follows the normal signup-credit policy.
How many requests can my credits cover?
Check account balance and source pricing. Request counts depend on the source, and mixed-source tasks share one balance. YouTube Download is priced by downloaded bytes, not a fixed request count.
Sources and results
Why can my agent search but not download?
Download needs owner access, youtube_download permission and destination storage. Temporary trials and mcp:research OAuth do not include Download. An authorized owner API key can use it through CLI, HTTP or MCP.
Does Google Search return full webpages?
It returns search results and excerpts. Your app or agent reads the selected URLs.
Does FlashData generate video summaries or captions?
It retrieves metadata and existing captions. It does not generate missing captions; your model writes a summary from available results.
Still stuck? Send a minimal report
Save the HTTP error body or CLI JSON error from stderr as diagnostic.json. Extract identifiers only after a failed command. Keep keys, private query text and signed URLs out of the report. For non-JSON responses, report the HTTP status from diagnostic-status.txt.
flashdata auth status --json 2> diagnostic.json# A saved HTTP error or CLI --json error; local files only.
date -u '+%Y-%m-%dT%H:%M:%SZ'
jq '(.error // .) as $e | {
status: ($e.httpStatus // $e.status),
code: $e.code,
requestId: $e.requestId,
runId: (.runId // $e.runId),
jobId: $e.remoteId,
retryAfter: $e.retryAfter
} | with_entries(select(.value != null))' diagnostic.jsonUTC time:
Client + version:
Source + stage (auth / submit / poll / fetch):
HTTP status + error code:
Request ID / job ID / run ID:
Submission outcome: accepted / rejected / unknown
Expected vs actual result: