Big SQL (Athena)

Query a large CSV with SQL from a single API call — for datasets past the ceiling of the in-process /v1/data/sql (DuckDB) op. You supply the file; it becomes a table named input; you send SELECT-only SQL; the query runs on AWS Athena and returns rows. Pricing is metered on bytes scanned and settles at the actual scan — you authorize a ceiling and pay what the query actually read.

curl -X POST https://api.relaystation.ai/v1/data/sql-large \
  -H 'Authorization: Bearer rs_live_<key>' \
  -H 'Idempotency-Key: sql-large-20260707' \
  -H 'Content-Type: application/json' \
  -d '{ "file": { "inputKey": "<key from upload-url>" },
        "sql": "SELECT category, COUNT(*) AS n FROM input GROUP BY category ORDER BY n DESC" }'

Or on the lodestone path — no account, a signed x402 payment instead of an API key:

curl -X POST https://api.relaystation.ai/v1/data/sql-large \
  -H 'X-Payment: <base64 EIP-3009 authorization>' \
  -H 'Idempotency-Key: sql-large-20260707' \
  -H 'Content-Type: application/json' \
  -d '{ "file": { "inputKey": "<key from upload-url>" },
        "sql": "SELECT * FROM input WHERE amount > 1000 LIMIT 100" }'

Request

POST /v1/data/sql-large:

Field	Type	Notes
`file`	input source, required	a CSV file, header row required. `{ "inline": "<base64>" }` ≤ 4 MiB, or `{ "inputKey": "..." }` for larger files (the usual reason to reach for this op)
`sql`	string, required	SELECT-only (or `WITH … SELECT`); 1–20000 chars. Your file is the table named `input`. A trailing semicolon is tolerated
`format`	enum	result shape: `csv` or `json`

SELECT / WITH only. Anything else (INSERT, DDL, PRAGMA, …) is rejected pre-charge with a 422 — this is a read-only query surface. Your CSV’s header row becomes the column names (lowercased, [a-z0-9_]-safe). For a large file, mint a presigned upload with POST /v1/cputools/upload-url and pass {"inputKey":"..."} — see Passing & receiving files.

Response

The query result comes back in the uniform JSON output envelope, plus a scan / billing receipt — the actual dataScannedBytes, the billed increments, the charged amount, and the ceiling. That receipt is why the price is auditable: you see exactly how many bytes Athena scanned.

Caps and the sync window

Scan cap — the query’s scan is bounded by data.sql_large.max_scan_mb (seed 500 MB). The authorized ceiling is computed from the input size (an upper bound on any single-file scan) and the operator cap.
Synchronous window — the call holds the connection while Athena runs, bounded by data.sql_large.sync_window_ms. A query that can’t finish in the window fails and the charge is reversed.
Failure discipline — user-caused failures (bad SQL, an unreadable CSV, a timeout) return a 422 and reverse the charge; infrastructure failures (throttle / upstream 5xx) return a 502 and reverse the charge. You pay only for a delivered result.

Billing

Metered on bytes scanned (per 100 MB increments), settle-at-actual: you authorize a ceiling at submit and pay the actual scan, never more than the ceiling. Priced per scanned unit; see Pricing for the current rate, or send an unauthenticated POST to read the exact price from the 402 challenge. Every billable call needs an Idempotency-Key; a same-key retry returns the cached result without re-charging.

Which SQL op?

In-process, smaller data → /v1/data/sql (DuckDB) — fast, no scan-metering, for files within its ceiling.
Large data, scan-metered → /v1/data/sql-large (Athena) — this op, for CSVs past the DuckDB ceiling.

MCP tools

Callable over MCP at https://api.relaystation.ai/mcp as data_sql_large. Same auth, same pricing as the HTTP route.

Data & SQL tools · Passing & receiving files · Pricing · x402 wire format · API reference