# Consulta tu cuenta y reutiliza resultados con el SDK

Comprueba el coste, conserva un registro de cada intento y lee los resultados guardados sin otra llamada a la API.

Referencia canónica: https://flashdata.dev/es/docs/guides/sdk-operations
Revisado: 2026-11-04 por FlashData

<a id="prepare"></a>

## Antes de empezar

Utilice el proyecto, instalado SDK y FLASHDATA_API_KEY desde su inicio rápido SDK. Elija un idioma a continuación. Cada nuevo directorio de ejecución representa una búsqueda prevista; reutilizando un directorio existente para antes de hacer cualquier solicitud.

- [Go SDK setup](https://flashdata.dev/es/docs/guides/flashdata-go/reference.md)
- [Python SDK](https://flashdata.dev/es/docs/guides/flashdata-python/reference.md)
- [TypeScript SDK](https://flashdata.dev/es/docs/guides/flashdata-typescript/reference.md)

<a id="check"></a>

## 1. Compruebe el acceso y el costo actual

Ahorre y ejecute el cheque para su SDK. Lee permisos, saldo y el precio de una búsqueda Google. Continúe sólo después de que se haya aprobado el cheque de acceso; estos cheques no presentan una consulta pagada o créditos de reserva.

### Python

#### check_access.py

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

#### Linux / macOS

```bash
.venv/bin/python check_access.py
```

#### Windows PowerShell

```powershell
.\.venv\Scripts\python.exe check_access.py
```


### TypeScript / JavaScript

#### check-access.mjs

```javascript
import { 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;
}
```

#### Corre

```bash
node check-access.mjs
```


### Go

Crear cmd/check y guardar este archivo allí.

#### cmd/check/main.go

```go
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.")
}
```

#### Corre

```bash
go run ./cmd/check
```



<a id="save"></a>

## 2. Corre con un nuevo directorio de salida

Ejecute uno de estos programas después de que el cheque pase. Crea el directorio antes de enviar, registra la solicitud, luego guarda la respuesta. Mantenga el directorio en el fracaso: borrarlo o elegir uno nuevo permite otra consulta facturable.

### Python

#### archive_search.py

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

#### Linux / macOS

```bash
.venv/bin/python archive_search.py runs/research-001
```

#### Windows PowerShell

```powershell
.\.venv\Scripts\python.exe archive_search.py runs/research-001
```


### TypeScript / JavaScript

Guarde este programa Node ESM en un proyecto JavaScript o TypeScript. Utiliza el mismo paquete instalado @flashdata-dev/sdk.

#### archive-search.mjs

```javascript
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;
}
```

#### Corre

```bash
node archive-search.mjs runs/research-001
```


### Go

Cree cmd/archive para que este punto de entrada se mantenga separado de su programa Quickstart.

#### cmd/archive/main.go

```go
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
}
```

#### Corre

```bash
go run ./cmd/archive runs/research-001
```



<a id="files"></a>

### Archivos previstos

El éxito imprime la ruta y el uso del resultado guardados. result.json debe tener status: done; Google los resultados están en results[].organic[]. Una matriz orgánica vacía es válida. Un reportado API o error de transporte se guarda en error.json; intent.json sigue siendo el registro de pre-submission original.

#### Un intento exitoso

```text
run/research-001/
  request.json Fuente, consulta y parámetros
  intent.json # Intento comenzar el tiempo
  result.json # Respuesta completa, incluyendo resultados y uso
```


<a id="read"></a>

## 3. Lea la salida guardada

Lea result.json para el análisis, resúmenes y trabajo UI. Estos comandos utilizan sólo archivos locales. Reaccionar la búsqueda con el mismo directorio se detiene antes de una llamada de red; no coordina diferentes máquinas o recupera una respuesta del servidor perdido.

### Bash

#### Lea localmente

```bash
cat runs/research-001/result.json
```


### PowerShell

#### Lea localmente

```powershell
Get-Content -Raw -LiteralPath './runs/research-001/result.json'
```


### Go: resultados de tipo

Crear cmd/read y guardar este decodificador allí. Lee el archivo e imprime los títulos de fuente y URLs sin construir un cliente o hacer una solicitud API.

#### cmd/read/main.go

```go
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)
}
```

#### Decodificar la respuesta guardada

```bash
go run ./cmd/read runs/research-001/result.json
```


- [Parse Google Resultados de búsqueda](https://flashdata.dev/es/docs/sources/google_search/reference.md)
- [Formatos de resultados compartidos](https://flashdata.dev/es/docs/guides/response-formats/reference.md)

<a id="errors"></a>

## Decidir qué hacer después de un fracaso

| Lo que tienes | Siguiente acción |
| --- | --- |
| Directorio existente / EEXIST | Inspeccione sus archivos. No se envió ninguna nueva consulta por este intento. |
| result.json, status: done | Leer y procesar la respuesta guardada. Reutilizar su uso como un recibo de la carga original. |
| error.json con 401 / 403 / 402 | Fijar el acceso, los permisos de origen o el equilibrio antes de planificar un nuevo intento. |
| 429 / retryAfter | Espere como se instruyó y reducir la tasa de solicitud. Revise el intento fallido antes de seleccionar un nuevo directorio de ejecución. |
| Sumisión desconocida / intención solamente / error de escritura | El trabajo ya puede ser aceptado. Mantenga el directorio e inspeccione Historia o un trabajo conocido ID antes de enviar otra consulta. |

- [Solicitud de historia](https://flashdata.dev/app/jobs)
- [Decisiones de recuperación](https://flashdata.dev/es/docs/guides/agent-recovery/reference.md)

<a id="async"></a>

## Async clients and background jobs

| Necesidad | Uso |
| --- | --- |
| Mantener un bucle de evento receptivo | El cliente async de SDK / espera llamadas. Una consulta en tiempo real todavía completa en su respuesta HTTP. |
| Reanuda después de las salidas del proceso de llamada | Presentar un trabajo de fondo una vez, guardar su ID remoto, luego leer estado y resultados. |
| Ejecutar en un horario | Utilice el acceso del propietario y los registros de ejecución de aplicaciones duraderas, o la revista de ejecución existente de CLI. |

- [Flujo de trabajo de Async y lotes](https://flashdata.dev/es/docs/guides/async-batch/reference.md)
- [Tareas recurrentes](https://flashdata.dev/es/docs/guides/recurring-tasks/reference.md)
