Run ScopeQL with the HTTP statements API

Run ScopeQL from any backend that can send HTTPS requests. Submit a statement, inspect its state, and poll or cancel it as needed. For writes, append rows over HTTP; for table definitions, use the Catalog API.

Before running the examples, set the base URL and API key. Follow the shared errors and retries contract when a request fails or its outcome is uncertain.

Submit a statement

This query verifies access without creating a table or writing data:

curl --fail-with-body --silent --show-error \
  "$SCOPEDB_ENDPOINT/v1/statements" \
  -H "Authorization: Bearer $SCOPEDB_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "statement": "SELECT 1 AS ready",
  "format": "json",
  "max_elapsed_seconds": 30
}
JSON

Inspect status in the response. When it is finished, the result has one ready column and a row containing "1". When it is pending or running, poll the returned statement ID. An HTTP success response alone does not mean the query finished successfully.

The request body accepts these fields:

Field	Required	Description
`statement`	Yes	One ScopeQL statement.
`format`	Yes	Use `json` for the result format documented here.
`statement_id`	No	A caller-selected UUID. ScopeDB creates one if omitted. This identifies execution; it is not an idempotency key.
`max_elapsed_seconds`	No	Positive, finite seconds from submission, including queueing and execution. Defaults to 3,600 seconds.
`max_estimated_seconds`	No	Positive, finite seconds allowed for the estimated execution duration. Omit it to leave this estimate limit unset.

Use max_elapsed_seconds for new clients. The older exec_timeout duration field is a compatibility alias and cannot be combined with it. A client-side HTTP timeout stops waiting for a response; it does not cancel execution in ScopeDB.

The response is a snapshot of the statement's current state:

Field	Description
`statement_id`	UUID used to poll or cancel the statement.
`status`	One of the five states below.
`created_at`	Timestamp for the statement.
`progress`	Completion and scan counters reported while the statement runs.
`result_set`	Present when `status` is `finished`.
`error`	Present when `status` is `failed`; contains `code`, `message`, and optional `details`.

Statement states

State	Meaning	What the client should do
`pending`	Accepted and waiting to run.	Poll the statement ID.
`running`	Execution is in progress.	Continue polling with a delay.
`finished`	Execution completed successfully.	Read `result_set`.
`failed`	Execution ended with an error.	Inspect `error.code` and `error.message`; stop polling.
`cancelled`	Execution was cancelled.	Stop polling. A cancellation message is not required.

finished, failed, and cancelled are terminal. An HTTP 2xx response only means the API request succeeded; it does not make failed or cancelled statements successful. Always inspect status.

Poll a statement

Poll only while the submit response is pending or running:

curl --fail-with-body --silent --show-error \
  "$SCOPEDB_ENDPOINT/v1/statements/<statement-id>?format=json" \
  -H "Authorization: Bearer $SCOPEDB_API_KEY"

Replace <statement-id> with the UUID from submission. Use an increasing delay with jitter instead of a tight loop. Keep the statement_id with application logs or active job state so later polling and support reports can be correlated. Stop when the state is terminal or the application's waiting deadline is reached.

If the submit response is already terminal, consume that response directly. Statements that finish within the submit request are not necessarily retained for a later GET. In particular, a VALUES ... INSERT INTO statement returns its terminal result without creating a pollable statement record.

For the connection test, the finished snapshot contains this result_set:

{
  "metadata": {
    "fields": [
      { "name": "ready", "data_type": "int" }
    ],
    "num_rows": 1
  },
  "format": "json",
  "rows": [
    ["1"]
  ]
}

metadata.fields defines the column order and type. Each entry in rows is an array in that order. JSON cell values are strings or null; convert them using the corresponding data_type in your client. For example, the integer result above is "1", not the JSON number 1. Empty rows means the query succeeded without returning rows. The SDKs provide result conversion helpers.

Cancel a statement

curl --fail-with-body --silent --show-error -X POST \
  "$SCOPEDB_ENDPOINT/v1/statements/<statement-id>/cancel?format=json" \
  -H "Authorization: Bearer $SCOPEDB_API_KEY"

Passing format=json returns a statement snapshot in the same shape as submission and polling. Treat cancellation as a request and inspect status: execution can race with cancellation. Only cancelled confirms cancellation; if the snapshot is still active, continue polling. Closing the HTTP connection does not cancel the server statement.