Skip to content
EN
Get API key
Browse documentation

API reference

Realtime and async

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.

ModeUse whenWhat you receive
RealtimeA search result is needed in the current interaction.The result body in the same HTTP response.
AsyncWork should continue after your process disconnects, or you are downloading media.A job ID immediately; fetch status and results separately.
Request lifecycle
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 → results

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

Python · install once
python3 -m pip install requests

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

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))

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

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))
Receipt fields · abbreviated example
{
  "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.statusNext action
pending / processingWait, then check the same job ID again.
completedRetrieve the saved result.
failedRead job.error. Fix the cause before submitting new work.

Save as job_status.py and run python3 job_status.py.

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"))

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

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))

Handle delays and failures

SituationWhat to do
Submission timed outA 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_readyKeep polling status. Do not create another job.
422 · result_not_readyThe job failed. Read job.error before retrying.
429Honor Retry-After or retry_after; reduce submission rate when pending capacity is full.
410 · result_expiredStored results expire 24 hours after completion. Use your saved copy.