Skip to content
EN
Get API key
Browse documentation

Get started

API quickstart

Call Google Search and YouTube APIs directly over HTTP. Send one request and read the JSON response; no SDK is required.

  1. Authenticate

    Create an account, verify your email and create a key with Google Search permission. You can reuse an existing key.

    Run this in your terminal and paste your key at the hidden prompt. Skip it if FLASHDATA_API_KEY is already set.

    Set your key
    # Bash: paste the key into a hidden prompt, not into this command.
    read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
    printf '\n'
    export FLASHDATA_API_KEY
  2. Run a search

    Choose a client and run the example in the same terminal. Each sends one POST request to https://data.flashdata.dev/v1/queries/realtime and prints JSON. Authenticate with X-API-Key; send JSON with Content-Type: application/json.

    cURL 7.76+ · Bash on Linux, macOS or Git Bash. Paste and run.

    Search · Bash / cURL
    curl --fail-with-body --silent --show-error --max-time 70 \
      --request POST https://data.flashdata.dev/v1/queries/realtime \
      --header "X-API-Key: $FLASHDATA_API_KEY" \
      --header 'Content-Type: application/json' \
      --data '{
      "source": "google_search",
      "query": "battery recycling research",
      "params": {
        "num": 5
      }
    }'
  3. Check the result

    Confirm HTTP success and status: done. Read source titles, links and snippets in results[].organic, and the charge in usage.credits.

    An empty results or organic list with status: done is a valid empty result.

    Example response
    {
      "source": "google_search",
      "status": "done",
      "results": [
        {
          "organic": [
            {
              "title": "Battery recycling research",
              "link": "https://example.org/recycling",
              "snippet": "An example search excerpt."
            }
          ]
        }
      ],
      "usage": {
        "credits": 0.02
      }
    }
    status
    "done" confirms the query finished successfully.
    results[0].organic[]
    Search results. Check that results is nonempty before indexing it.
    title / link / snippet
    Source title, URL and excerpt.
    usage.credits
    Actual credits charged for this query.

Save a response for debugging

To capture the next intended request, add these options to the cURL command above. Inspect the files before deciding to retry a failed request.

cURL
--dump-header response-headers.txt --output result.json

Check access and credits

These GET requests read identity, balance and pricing without using query credits. Expect HTTP 200 and check the fields below before submitting paid work.

Account reads: https://api.flashdata.dev/v2. Data requests: https://data.flashdata.dev/v1. Both use X-API-Key; JSON POST requests also use Content-Type: application/json.

Free checks · Bash
(
for endpoint in 'identity' 'balance' 'pricing?source=google_search&request_count=1'; do
  printf '\n%s\n' "$endpoint"
  curl --fail-with-body --silent --show-error --max-time 20 \
    --header "X-API-Key: $FLASHDATA_API_KEY" \
    --write-out '\nHTTP %{http_code}\n' \
    "https://api.flashdata.dev/v2/api-access/$endpoint" || exit
done
)
identity
Confirm the intended accountId, access: "ready", scopes containing "google_search", and any expiresAt. accountType is "owned" for an owner key or "temporary" for a trial key.
balance
Read availableCredits. All keys for this account use the same balance.
pricing
For prices[0], confirm source is google_search and available is true. Compare estimatedCredits for requestCount: 1 with availableCredits. Prices and balances can change before submission.

Next steps

If a step fails

Read the response printed in your terminal. JavaScript and Python report HTTP errors and Retry-After to stderr. Each example submits once; it does not automatically retry.

Command missing or unsupported option
Check the required version in the selected example. Use PowerShell 7 rather than Windows PowerShell 5.1, or use Bash with cURL 7.76+. JavaScript needs Node 22+; Python needs 3.10+. Install the missing runtime from its official download page, reopen the terminal, then set the key again.
Missing key / 401
Set FLASHDATA_API_KEY in this process and check identity again. Supply the full active API key, without a Bearer prefix. If it expired or was revoked, use a current authorized credential; do not paste it into chat.
403
Check identity.scopes for google_search and access for ready. Request the missing permission from the owner; changing the source in the request does not grant access.
402
Read balance again and compare it with the current price. The owner can review Billing. An exhausted trial needs owner access through claiming; creating a replacement trial is not recovery.
400 / 422
Read the returned error message. Check the exact data host, POST method, Content-Type and JSON field names. Use straight quotes and a numeric params.num, then correct the rejected request.
429
Respect Retry-After if present; otherwise use a bounded backoff and reduce concurrency. Do not loop rapidly, create new keys or register another trial to bypass the limit.
HTTP 200 with failed status or error
Read the error in the body and preserve any request or job ID. Do not treat a parsed JSON body as a successful task or automatically resubmit it.
Empty results
If status is done, authentication worked. Keep the empty result or try a broader query as a new paid request.
Timeout, connection loss, 5xx or HTML instead of JSON
A POST may have been accepted even if its response was lost. Check History for the original query and preserve any returned IDs before deciding to resend. Free GET checks can be retried. Confirm the URL uses data.flashdata.dev, not the website host, and do not disable TLS verification.