Onchain

Submit Asynchronous Blockchain SQL Job

Accepts a read-only SQL query for durable background execution. Returns a stable job and ClickHouse query ID immediately. Reusing the same Idempotency-Key, or submitting SQL equivalent after whitespace and operator-spacing normalization with the same max_rows while its retained job exists, returns the existing job without starting another execution. Accepted jobs remain queued while the owner's cluster-wide ClickHouse execution budget is occupied by synchronous or asynchronous work.

post/gateway/v1/onchain/sql/jobs

Headers

Idempotency-Keystring

Stable client-generated key. Reusing it returns the existing job without starting another query.

Request body

$schemastring uri

A URL to the JSON Schema for this object.

max_rowsinteger

Maximum number of result rows to retain

sqlstring required

Exact read-only ClickHouse SQL to execute asynchronously. The submitted SQL and date range are preserved.

Example request

{
  "$schema": "https://example.com/schemas/HumaOnchainSQLJobCreateInputBody.json",
  "max_rows": 1000,
  "sql": "SELECT block_date, project, symbol, apy FROM agent.ethereum_yields_daily WHERE block_date >= today() - 30 ORDER BY apy DESC"
}

Response

Accepted

$schemastring uri

A URL to the JSON Schema for this object.

Example response

{
  "$schema": "https://example.com/schemas/DataObjectResponseAsyncSQLJobResponse.json"
}

Changes

No recorded changes to this endpoint across all 2 revisions of this API.