Browse documentation
API reference
Get results in the response, or submit a job and retrieve them later. Choose how your application or agent waits for work.
On this page
Choose a request mode
Google Search and YouTube Data support both modes. YouTube Download requires async, Batch or Bulk; it does not support realtime. The source parameters stay the same when switching from realtime to async.
| Mode | Use when | What you receive |
|---|---|---|
| Realtime | A search result is needed in the current interaction. | The result body in the same HTTP response. |
| Async | Work should continue after your process disconnects, or you are downloading media. | A job ID immediately; fetch status and results separately. |
Realtime POST data.flashdata.dev/v1/queries/realtime → results
Async POST data.flashdata.dev/v1/queries → job ID
GET api.flashdata.dev/v2/jobs/{id} → status
GET api.flashdata.dev/v2/jobs/{id}/results → resultsSend a request
Set FLASHDATA_API_KEY to a key that allows google_search. Choose realtime or async; each submission runs one billable search. Keep scripts, receipts and results in the same new working folder.
Python examples use Python 3.10+ and Requests. Each script runs independently and reads saved files from earlier steps. The cURL alternative needs Bash, cURL 7.76+ and jq.
python3 -m pip install requestsRealtime: get the result now
POST /v1/queries/realtime returns status: done and a results array. Read result.json; no polling is needed.
Save as realtime.py and run python3 realtime.py.
import json
import os
from pathlib import Path
import requests
response = requests.post(
"https://data.flashdata.dev/v1/queries/realtime",
headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
json={"source": "google_search", "query": "battery recycling research", "params": {"num": 5}},
timeout=120, allow_redirects=False,
)
response.raise_for_status()
result = response.json()
Path("result.json").write_text(json.dumps(result, indent=2), encoding="utf-8")
print(json.dumps(result, indent=2))curl --fail-with-body --silent --show-error \
'https://data.flashdata.dev/v1/queries/realtime' \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--header 'Content-Type: application/json' \
--data '{"source":"google_search","query":"battery recycling research","params":{"num":5}}' \
--output result.json &&
jq '{source, status, results, usage}' result.jsonAsync: save a job receipt
POST /v1/queries returns a pending job receipt, not the search results. Save submission.json and continue with the status and result requests below.
Save as submit_async.py and run python3 submit_async.py.
import json
import os
from pathlib import Path
import requests
response = requests.post(
"https://data.flashdata.dev/v1/queries",
headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
json={"source": "google_search", "query": "battery recycling research", "params": {"num": 5}},
timeout=30, allow_redirects=False,
)
response.raise_for_status()
result = response.json()
Path("submission.json").write_text(json.dumps(result, indent=2), encoding="utf-8")
print(json.dumps(result, indent=2)){
"id": "job_EXAMPLE",
"source": "google_search",
"status": "pending"
}curl --fail-with-body --silent --show-error \
'https://data.flashdata.dev/v1/queries' \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--header 'Content-Type: application/json' \
--data '{"source":"google_search","query":"battery recycling research","params":{"num":5}}' \
--output submission.json &&
jq '{id, source, status, links}' submission.json{
"id": "job_EXAMPLE",
"source": "google_search",
"status": "pending"
}Check an async job
Read job.status using the ID in submission.json. For pending or processing, wait for the Retry-After delay before checking again; Python prints it and cURL saves it in status-headers.txt. Use backoff if no hint is returned. A successful status request does not mean the job has completed.
| job.status | Next action |
|---|---|
| pending / processing | Wait, then check the same job ID again. |
| completed | Retrieve the saved result. |
| failed | Read job.error. Fix the cause before submitting new work. |
Save as job_status.py and run python3 job_status.py.
import json
import os
from pathlib import Path
import requests
job_id = json.loads(Path("submission.json").read_text(encoding="utf-8"))["id"]
response = requests.get(
f"https://api.flashdata.dev/v2/jobs/{job_id}",
headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
timeout=30, allow_redirects=False,
)
response.raise_for_status()
Path("job.json").write_text(json.dumps(response.json(), indent=2), encoding="utf-8")
print(json.dumps(response.json()["job"], indent=2))
print("Retry-After:", response.headers.get("Retry-After", "not provided"))JOB_ID=$(jq -er '.id' submission.json)
curl --fail-with-body --silent --show-error \
"https://api.flashdata.dev/v2/jobs/$JOB_ID" \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--dump-header status-headers.txt --output job.json &&
jq '.job | {id, source, status, error}' job.jsonRetrieve the completed result
Run this after job.status is completed. The default results response is 302: Location points to a signed storage URL. The two requests below keep your API key on FlashData and save the original JSON to result.json. For YouTube Download, this JSON describes media delivered to your storage; it is not the video or audio file.
Save as job_result.py and run python3 job_result.py.
import json
import os
from pathlib import Path
import requests
receipt = json.loads(Path("submission.json").read_text(encoding="utf-8"))
job_id = receipt["id"]
response = requests.get(
f"https://api.flashdata.dev/v2/jobs/{job_id}/results",
headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
timeout=30, allow_redirects=False,
)
response.raise_for_status()
if response.status_code != 302:
raise RuntimeError(f"Expected a result redirect, got {response.status_code}")
url = response.headers["Location"]
if not url.startswith("https://"):
raise ValueError("Expected an HTTPS storage URL")
# A separate request: no FlashData key is sent to storage.
result = requests.get(url, timeout=120)
result.raise_for_status()
data = result.json() # Requests automatically decodes Content-Encoding: gzip.
Path("result.json").write_text(json.dumps(data, indent=2), encoding="utf-8")
print(json.dumps(data, indent=2))JOB_ID=$(jq -er '.id' submission.json)
RESULT_URL=$(curl --fail-with-body --silent --show-error \
"https://api.flashdata.dev/v2/jobs/$JOB_ID/results" \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--output /dev/null --write-out '%{redirect_url}') &&
curl --fail-with-body --silent --show-error --compressed --proto '=https' \
"${RESULT_URL:?Expected a signed result URL}" --output result.json &&
jq '{source, status, results, usage}' result.jsonHandle delays and failures
| Situation | What to do |
|---|---|
| Submission timed out | A POST may already have been accepted. Check your saved receipt and account history before resubmitting; repeated POSTs can create new billable jobs. |
| 409 · result_not_ready | Keep polling status. Do not create another job. |
| 422 · result_not_ready | The job failed. Read job.error before retrying. |
| 429 | Honor Retry-After or retry_after; reduce submission rate when pending capacity is full. |
| 410 · result_expired | Stored results expire 24 hours after completion. Use your saved copy. |