SQL

sql.execute

Run a SQL query over all of Sui

Details

Endpoint: POST /v1/sql/execute
Credits: varies
Pricing: Depends on the input and the size of the result. The description says how.
Rate class: Heavy. Counts against your heavy requests per second.
Also called: /api/v1/sql/execute

Starts a run of one SQL SELECT over the public tables (every transaction, event, object version and balance change since genesis, about a second behind the chain) and returns an execution_id. Poll /v1/execution/{execution_id}/status, then read /v1/execution/{execution_id}/results. Credits are charged when the run ends: 20 plus 1 per 50 MB read; a reused result (max_age) costs 2. Without a key, runs come out of the small daily keyless allowance.

Parameters

Name	Type	Description
dialect	string	tide (default), or trino for Trino SQL written against the standard Sui table names; it is translated before it runs.One of "tide", "trino".
sqlrequired	string	One SQL SELECT over the public tables. Use {{name}} for parameters. 0x ids (64 hex) can be compared directly: WHERE sender = 0x1a2b...
params	object	Values for {{name}} parameters: { name: value } or { name: { type: text \| number \| date \| list, value } }.
max_age	integer	Reuse a finished result of the same SQL and params up to this many seconds old (costs 2 credits). Default 0, always run.
wait_ms	integer	Wait up to this many milliseconds (max 30000) for the run to finish and return its status in the same response.

Request

Send your key in the x-api-key header, or leave it out to use the keyless tier.

curl

curl -X POST "https://api.tide.ad/v1/sql/execute" \
  -H "x-api-key: YOUR_API_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"
}'

TypeScript

const res = await fetch("https://api.tide.ad/v1/sql/execute", {
  method: "POST",
  headers: {
    "x-api-key": process.env.TIDE_API_KEY!,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    "sql": "SELECT sequence_number, block_time, total_transaction_blocks FROM sui.checkpoints ORDER BY sequence_number DESC LIMIT 5"
  }),
});
const data = await res.json();

Response

JSON

{
  "execution_id": "0101A1A5B78D3AABF922700F5F30C8195F",
  "state": "QUERY_STATE_EXECUTING"
}