---
title: "Submit Asynchronous Blockchain SQL Job"
method: POST
path: "/gateway/v1/onchain/sql/jobs"
tags: ["Onchain"]
---

# Submit Asynchronous Blockchain SQL Job

`POST /gateway/v1/onchain/sql/jobs`

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.

## Headers

- `Idempotency-Key` string — Stable client-generated key. Reusing it returns the existing job without starting another query.

## Request body

- HumaOnchainSQLJobCreateInputBody
  - `$schema` string, uri — A URL to the JSON Schema for this object.
  - `max_rows` integer — Maximum number of result rows to retain
  - `sql` string, required — Exact read-only ClickHouse SQL to execute asynchronously. The submitted SQL and date range are preserved.

## Response `202`

Accepted

- DataObjectResponseAsyncSQLJobResponse
  - `$schema` string, uri — A URL to the JSON Schema for this object.
  - `data` AsyncSQLJobResponse, required
    - `cancellation_requested` boolean, required — Whether cancellation has been durably requested and is awaiting worker confirmation
    - `created_at` integer, required — Unix timestamp in seconds
    - `csv_url` string
    - `elapsed_ms` integer, required
    - `error` AsyncSQLJobError
      - `code` string, required — Stable machine-readable error code
      - `message` string, required — Human-readable failure detail
    - `estimated_bytes` integer — Approximate total bytes derived from ClickHouse progress
    - `estimated_rows` integer — Approximate total rows ClickHouse expects to read
    - `executed_sql` string, required — Final SQL executed after server row and scan limits are applied
    - `expires_at` integer, required — Unix timestamp in seconds
    - `external_request_id` string — Optional caller-supplied correlation identifier
    - `finished_at` integer — Unix timestamp in seconds
    - `job_id` string, uuid, required
    - `max_rows` integer, required
    - `parameters` object, required — ClickHouse bind parameters; empty because this endpoint accepts complete SQL text
    - `poll_url` string
    - `processed_bytes` integer, required
    - `processed_rows` integer, required
    - `progress_percent` number, double — Approximate completion percentage when ClickHouse reports a total-row estimate
    - `query_id` string, uuid, required
    - `recommended_action` string, required
    - `request_id` string, required — Caller-visible request correlation identifier
    - `result_url` string
    - `retry_after_ms` integer
    - `retryable` boolean, required
    - `row_count` integer
    - `sql` string, required — Exact submitted SQL
    - `started_at` integer — Unix timestamp in seconds
    - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'canceled', required
  - `meta` ObjectResponseMeta, required
    - `cached` boolean, required — Whether this response was served from cache
    - `credits_used` integer, required — Credits deducted for this request
    - `empty_reason` string — Hint explaining why the data array is empty, when applicable

## Other responses

- `429` — Tenant queue capacity exceeded or the equivalent-query failure circuit is open
- `default` — Error

---

[API](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api.md) · [All operations](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/asksurf/asksurf-public-rest-api/revisions/4153a9cb5145/schema)