Skip to content
EN
Get API key
Browse documentation

Get started

FAQ & troubleshooting

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.

Free account reads
flashdata --version
flashdata doctor --offline
flashdata auth status --json

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.

Locate the executable
command -v flashdata
flashdata --version
flashdata doctor --offline

401 / 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.

  1. 401: check for an expired, revoked or incorrectly configured key. 403: compare the requested source with the identity's scopes.
  2. REST and SDKs use X-API-Key. An MCP OAuth token cannot replace an API key. For temporary access, use the claim recovery below.
Replace and verify a saved owner key
flashdata auth login --replace
flashdata auth status --json

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

Finish and verify
flashdata auth finish --wait --timeout 10m
flashdata auth status --json

402: 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.

Free account reads
flashdata account balance
flashdata account pricing --source google_search --request-count 1

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.

Capture the response · Bash / cURL / jq
# 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
)
Inspect account capacity
flashdata account limits

400 / 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.

Validate without a paid submission
flashdata query --input request.json --mode async --dry-run --json

Job 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 errorNext action
pending / processingWait on the same job; do not submit it again.
completedFetch and save the existing result.
failedInspect job.error before submitting corrected work.
404Check the job ID and the submitting account.
409Results are not ready. Keep polling the same job.
410Stored JSON expired after 24 hours. Use your saved copy; delivered media has its own storage retention.
Inspect the saved job · Bash / jq
# 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
)
Still running · use the returned JOB_ID
flashdata jobs wait JOB_ID
Completed · use a new output filename
flashdata jobs result JOB_ID --output recovered-result.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.

Inspect first · replace RUN_ID
flashdata runs show RUN_ID
Recover confirmed accepted work
flashdata runs recover RUN_ID

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

Inspect the original run
flashdata runs show RUN_ID

Empty search, missing captions or unreadable download

These commands only read local result files, not the CLI's stdout envelope.

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

Check configuration
codex mcp list
Only when OAuth login is required
codex mcp login flashdata --scopes mcp:research

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

Check the default CLI skill bundle
flashdata skills verify --agent codex

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

Capture a free CLI access check · Bash
flashdata auth status --json 2> diagnostic.json
Extract error identifiers · Bash / jq
# 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.json
Support report
UTC 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: