SQL API

Write queries in the editor at /queries/new, or run them from code. The same engine, tables, limits and credits serve both. Every result says which checkpoint its data reflects and how far behind the chain that was.

Quick start

curl -s -X POST https://api.tide.ad/v1/sql/execute \
  -H "x-api-key: $TIDE_KEY" -H "content-type: application/json" \
  -d '{"sql": "SELECT sequence_number, block_time, total_transaction_blocks FROM sui.checkpoints ORDER BY sequence_number DESC LIMIT 5", "wait_ms": 20000}'

Without wait_ms you get an execution_id at once. Poll its status, then page through the rows:

curl -s "https://api.tide.ad/v1/execution/$ID/status?wait_ms=25000" -H "x-api-key: $TIDE_KEY"
curl -s "https://api.tide.ad/v1/execution/$ID/results?limit=1000&offset=0" -H "x-api-key: $TIDE_KEY"
curl -s "https://api.tide.ad/v1/execution/$ID/results/csv" -H "x-api-key: $TIDE_KEY" > rows.csv

States are QUERY_STATE_PENDING, QUERY_STATE_EXECUTING, QUERY_STATE_COMPLETED, QUERY_STATE_FAILED and QUERY_STATE_CANCELLED. A failed run has error.message with error.metadata.line and column. Every path also works under /api/v1/, so clients written for the common analytics API shape work by changing the base URL.

Tables

Raw tables use the standard Sui table names and columns (sui.transactions, sui.events, sui.objects, sui.move_call, sui.checkpoints, sui.transaction_objects, sui.move_package). Curated tables sit next to them: coin transfers, DEX trades with USD at trade time, prices by hour and day, NFT trades, lending, launchpads, labels, SuiNS names, validators, staking and Walrus. The editor's schema browser lists every column with its type and meaning, and GET /v1/sql/schema returns the same list.

Ids, types and time

• Addresses and object ids are 32-byte values and print as 0x plus 64 hex. Compare them directly: WHERE sender = 0x1a2b... (quoted or not) uses the table's index.
• Move types are full width: 0x0000...0002::sui::SUI. In the Trino dialect, short forms like 0x2::sui::SUI are expanded for you.
• Amounts are raw integers in the coin's smallest unit (SUI has 9 decimals). Curated tables add decimal amounts and USD.
• Times are UTC. Large tables are ordered by checkpoint, so a checkpoint range is the fastest filter. Join sui.day_checkpoints to turn dates into checkpoint ranges.

Parameters

Write {{name}} in the SQL and send values in params, either plain ({"days": 7}) or typed ({"from": {"type": "date", "value": "2026-01-01"}}). Types are text, number, date and list. Values are escaped, never pasted as SQL.

Trino dialect

Send "dialect": "trino" to run a query written in the Trino dialect against the standard Sui table names, as is. Functions like date_trunc, from_unixtime, approx_distinct, try_cast, json_extract_scalar and CROSS JOIN UNNEST are translated, and dbt wrappers are stripped. POST /v1/sql/translate shows the translation without running it.

Saved queries

Save a query with POST /v1/query (name, SQL, parameters, visualizations). Run it with POST /v1/query/{query_id}/execute and read its latest results without running it with GET /v1/query/{query_id}/results. Public queries can be forked and starred.

Dashboards

GET /v1/dashboard/{slug} returns a dashboard with every widget's query, visualization and latest rows inline. Dashboards with a refresh schedule re-run on their own; POST /v1/dashboard/{slug}/run runs one with your filter values.

Limits and credits

A run costs 20 credits plus 1 per 50 MB it reads, charged when it finishes; reusing a recent identical result costs 2. Runs at once, time limit, data read and result size depend on the plan, see Plans and credits. Without a key, SQL runs one at a time with 15 s, 20 GB and 10,000 rows per run. GET /v1/sql/limits returns yours.

Methods