Browse documentation
Get started
Check cost, keep a record of each attempt and read saved results without another API call.
On this page
Before you start
Use the project, installed SDK and FLASHDATA_API_KEY from your SDK quickstart. Choose one language below. Each new run directory represents one intended search; reusing an existing directory stops before making any request.
1. Check access and current cost
Save and run the check for your SDK. It reads permissions, balance and the price of one Google Search. Continue only after Access check passed; these checks do not submit a paid query or reserve credits.
import os
import sys
from flashdata import FlashData, APIError
def main():
key = os.environ.get("FLASHDATA_API_KEY", "").strip()
if not key:
raise RuntimeError("Set FLASHDATA_API_KEY in this terminal.")
with FlashData(api_key=key) as client:
access = client.account.access()
if "google_search" not in access["sources"]:
raise RuntimeError("This key needs google_search permission.")
balance = client.account.balance()
pricing = client.account.pricing(source="google_search", request_count=1)
price = next((p for p in pricing["prices"]
if p["source"] == "google_search" and p["available"]), None)
cost = price.get("estimatedCredits") if price else None
if cost is None:
raise RuntimeError("No current price is available; stop here.")
available = balance["availableCredits"]
print(f"Available credits: {available}")
print(f"One search: {cost} credits")
if available < cost:
raise RuntimeError("Insufficient credits. Review Billing.")
print("Access check passed. No paid query submitted.")
if __name__ == "__main__":
try:
main()
except APIError as error:
print(f"HTTP {error.status_code}; code={error.code}; "
f"request_id={error.request_id}; Retry-After={error.retry_after}",
file=sys.stderr)
sys.exit(1)
except Exception as error:
print(f"{type(error).__name__}: {error}", file=sys.stderr)
sys.exit(1).venv/bin/python check_access.py.\.venv\Scripts\python.exe check_access.pyimport { FlashData, APIError } from '@flashdata-dev/sdk';
try {
const apiKey = process.env.FLASHDATA_API_KEY?.trim();
if (!apiKey) throw new Error('Set FLASHDATA_API_KEY in this terminal.');
const client = new FlashData({ apiKey });
const access = await client.account.access();
if (!access.sources.includes('google_search')) {
throw new Error('This key needs google_search permission.');
}
const balance = await client.account.balance();
const pricing = await client.account.pricing({ source: 'google_search', request_count: 1 });
const price = pricing.prices.find(p => p.source === 'google_search' && p.available);
const cost = price?.estimatedCredits;
if (cost == null) throw new Error('No current price is available; stop here.');
console.log('Available credits:', balance.availableCredits);
console.log('One search:', cost, 'credits');
if (balance.availableCredits < cost) throw new Error('Insufficient credits. Review Billing.');
console.log('Access check passed. No paid query submitted.');
} catch (error) {
if (error instanceof APIError) {
console.error('HTTP', error.statusCode, 'code:', error.code,
'request_id:', error.requestId, 'Retry-After:', error.retryAfter);
} else {
console.error(error instanceof Error ? error.message : String(error));
}
process.exitCode = 1;
}node check-access.mjsCreate cmd/check and save this file there.
package main
import (
"context"
"fmt"
"log"
"os"
"slices"
"time"
flashdata "github.com/flashdatadev/flashdata-go"
)
func main() {
key := os.Getenv("FLASHDATA_API_KEY")
if key == "" {
log.Fatal("Set FLASHDATA_API_KEY in this terminal.")
}
client, err := flashdata.New(flashdata.Options{APIKey: key})
if err != nil {
log.Fatal(err)
}
ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
defer cancel()
identity, err := client.Account.Identity(ctx)
if err != nil {
log.Fatal(err)
}
if identity.Access != "ready" || !slices.Contains(identity.Scopes, flashdata.SourceGoogleSearch) {
log.Fatal("This key is not ready for google_search. Check its status and permissions.")
}
balance, err := client.Account.Balance(ctx)
if err != nil {
log.Fatal(err)
}
pricing, err := client.Account.Pricing(ctx, flashdata.PricingParams{
Source: flashdata.SourceGoogleSearch, RequestCount: 1,
})
if err != nil {
log.Fatal(err)
}
if len(pricing.Prices) != 1 || pricing.Prices[0].Source != "google_search" ||
!pricing.Prices[0].Available || pricing.Prices[0].EstimatedCredits == nil {
log.Fatal("A current Google Search price is unavailable. Do not submit yet.")
}
cost := *pricing.Prices[0].EstimatedCredits
fmt.Printf("Account: %s (%s)\n", identity.AccountID, identity.AccountType)
fmt.Printf("Available credits: %g\nOne search: %g credits\n", balance.AvailableCredits, cost)
if balance.AvailableCredits < cost {
log.Fatal("Insufficient credits. Check Billing or claim existing trial access.")
}
fmt.Println("Access check passed. No paid query submitted.")
}go run ./cmd/check2. Run with a new output directory
Run one of these programs after the check passes. It creates the directory before submitting, records the request, then saves the response. Keep the directory on failure: deleting it or choosing a new one allows another billable query.
import json
import os
import sys
from datetime import datetime, timezone
from pathlib import Path
from flashdata import FlashData, APIError, SubmissionUnknownError
def main():
key = os.environ.get("FLASHDATA_API_KEY", "").strip()
if not key:
raise RuntimeError("Set FLASHDATA_API_KEY before running.")
directory = Path(sys.argv[1] if len(sys.argv) > 1 else "runs/research-001")
directory.mkdir(mode=0o700, parents=True, exist_ok=False)
def save(name, value):
with (directory / name).open("x", encoding="utf-8") as output:
json.dump(value, output, ensure_ascii=False, indent=2)
request = {"source": "google_search", "query": "battery recycling research",
"params": {"num": 5}}
save("request.json", request)
save("intent.json", {"state": "dispatching",
"startedAt": datetime.now(timezone.utc).isoformat()})
try:
with FlashData(api_key=key) as client:
response = client.google.search(request["query"], **request["params"])
except (APIError, SubmissionUnknownError) as error:
detail = {"kind": type(error).__name__}
if isinstance(error, APIError):
detail.update(code=error.code, httpStatus=error.status_code,
requestId=error.request_id, retryAfter=error.retry_after)
save("error.json", detail)
raise RuntimeError("Inspect the saved attempt and History before retrying.") from None
save("result.json", response)
if response.get("status") != "done":
raise RuntimeError("Response saved; inspect its status before proceeding.")
print("Saved:", directory / "result.json")
print("Usage:", response.get("usage"))
if __name__ == "__main__":
try:
main()
except Exception as error:
print(f"{type(error).__name__}: {error}", file=sys.stderr)
sys.exit(1).venv/bin/python archive_search.py runs/research-001.\.venv\Scripts\python.exe archive_search.py runs/research-001Save this Node ESM program in either a JavaScript or TypeScript project. It uses the same installed @flashdata-dev/sdk package.
import { mkdir, writeFile } from 'node:fs/promises';
import { dirname, join } from 'node:path';
import { FlashData, APIError, SubmissionUnknownError } from '@flashdata-dev/sdk';
try {
const apiKey = process.env.FLASHDATA_API_KEY?.trim();
if (!apiKey) throw new Error('Set FLASHDATA_API_KEY before running.');
const directory = process.argv[2] || 'runs/research-001';
await mkdir(dirname(directory), { recursive: true });
await mkdir(directory, { mode: 0o700 }); // Existing attempt: stop before any API call.
const save = (name, value) => writeFile(join(directory, name),
JSON.stringify(value, null, 2), { flag: 'wx', mode: 0o600 });
const request = { source: 'google_search', query: 'battery recycling research',
params: { num: 5 } };
await save('request.json', request);
await save('intent.json', { state: 'dispatching', startedAt: new Date().toISOString() });
const client = new FlashData({ apiKey });
let response;
try {
response = await client.google.search({ query: request.query, ...request.params });
} catch (error) {
const detail = { kind: error instanceof SubmissionUnknownError
? 'SubmissionUnknownError' : error instanceof APIError ? 'APIError' : 'ClientError' };
if (error instanceof APIError) Object.assign(detail, {
code: error.code, httpStatus: error.statusCode,
requestId: error.requestId, retryAfter: error.retryAfter,
});
await save('error.json', detail);
throw new Error('Inspect the saved attempt and History before retrying.');
}
await save('result.json', response);
if (response.status !== 'done') throw new Error('Response saved; inspect its status.');
console.log('Saved:', join(directory, 'result.json'));
console.log('Usage:', response.usage);
} catch (error) {
console.error(error instanceof Error ? error.message : 'Inspect this attempt.');
process.exitCode = 1;
}node archive-search.mjs runs/research-001Create cmd/archive so this entry point stays separate from your Quickstart program.
package main
import (
"context"
"encoding/json"
"errors"
"fmt"
"os"
"path/filepath"
"time"
flashdata "github.com/flashdatadev/flashdata-go"
)
func main() {
if err := run(); err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}
}
func run() error {
key := os.Getenv("FLASHDATA_API_KEY")
if key == "" { return errors.New("set FLASHDATA_API_KEY before running") }
directory := "runs/research-001"
if len(os.Args) > 1 { directory = os.Args[1] }
if err := os.MkdirAll(filepath.Dir(directory), 0700); err != nil { return err }
if err := os.Mkdir(directory, 0700); err != nil { return err }
save := func(name string, value any) error {
file, err := os.OpenFile(filepath.Join(directory, name), os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0600)
if err != nil { return err }
err = json.NewEncoder(file).Encode(value)
closeErr := file.Close()
if err != nil { return err }
return closeErr
}
query := flashdata.GoogleSearchInput{Query: "battery recycling research",
Params: &flashdata.GoogleSearchParams{Num: flashdata.Ptr(int64(5))}}
if err := save("request.json", map[string]any{"source": "google_search",
"query": query.Query, "params": query.Params}); err != nil { return err }
if err := save("intent.json", map[string]string{"state": "dispatching",
"startedAt": time.Now().UTC().Format(time.RFC3339)}); err != nil { return err }
client, err := flashdata.New(flashdata.Options{APIKey: key})
if err != nil { return err }
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
defer cancel()
result, err := client.Google.Search(ctx, query)
if err != nil {
detail := map[string]any{"kind": "ClientError"}
var api *flashdata.APIError
var unknown *flashdata.SubmissionUnknownError
if errors.As(err, &api) {
detail = map[string]any{"kind": "APIError", "code": api.Code,
"httpStatus": api.StatusCode, "requestId": api.RequestID, "retryAfter": api.RetryAfter}
} else if errors.As(err, &unknown) { detail["kind"] = "SubmissionUnknownError" }
if saveErr := save("error.json", detail); saveErr != nil { return saveErr }
return errors.New("inspect the saved attempt and History before retrying")
}
if err := save("result.json", result); err != nil { return err }
if result.Status != "done" { return errors.New("response saved; inspect its status") }
fmt.Printf("Saved: %s\nUsage: %+v\n", filepath.Join(directory, "result.json"), result.Usage)
return nil
}go run ./cmd/archive runs/research-001Expected files
Success prints the saved result path and usage. result.json should have status: done; Google results are in results[].organic[]. An empty organic array is valid. A reported API or transport error is saved to error.json; intent.json remains the original pre-submission record.
runs/research-001/
request.json # Source, query and parameters
intent.json # Attempt start time
result.json # Full response, including results and usage3. Read saved output
Read result.json for parsing, summaries and UI work. These commands use only local files. Rerunning the search with the same directory stops before a network call; it does not coordinate different machines or recover a lost server response.
cat runs/research-001/result.jsonGet-Content -Raw -LiteralPath './runs/research-001/result.json'Create cmd/read and save this decoder there. It reads the file and prints source titles and URLs without constructing a client or making an API request.
package main
import (
"encoding/json"
"fmt"
"log"
"os"
flashdata "github.com/flashdatadev/flashdata-go"
)
func main() {
filename := "runs/research-001/result.json"
if len(os.Args) > 1 { filename = os.Args[1] }
data, err := os.ReadFile(filename)
if err != nil { log.Fatal(err) }
var result flashdata.DataQueryResponse
if err := json.Unmarshal(data, &result); err != nil { log.Fatal(err) }
if result.Source != "google_search" || result.Status != "done" {
log.Fatal("Expected a completed Google Search response")
}
pages, err := flashdata.DecodeResults[flashdata.GoogleSearchPayload](&result)
if err != nil { log.Fatal(err) }
for _, page := range pages {
for _, hit := range page.Organic {
if hit.Title != nil && hit.Link != nil { fmt.Println(*hit.Title, *hit.Link) }
}
}
fmt.Printf("Original query credits: %g\n", result.Usage.Credits)
}go run ./cmd/read runs/research-001/result.jsonDecide what to do after a failure
| What you have | Next action |
|---|---|
| Existing directory / EEXIST | Inspect its files. No new query was sent by this attempt. |
| result.json, status: done | Read and process the saved response. Reuse its usage as a receipt of the original charge. |
| error.json with 401 / 403 / 402 | Fix access, source permissions or balance before planning a new attempt. |
| 429 / retryAfter | Wait as instructed and reduce the request rate. Review the failed attempt before selecting a new run directory. |
| Unknown submission / intent only / write failure | Work may already be accepted. Keep the directory and inspect History or a known job ID before sending another query. |
Async clients and background jobs
| Need | Use |
|---|---|
| Keep an event loop responsive | The SDK's async client / await calls. A realtime query still completes in its HTTP response. |
| Resume after the calling process exits | Submit a background job once, save its remote ID, then read status and results. |
| Run on a schedule | Use owner access and durable application run records, or the CLI's existing run journal. |