View execution status¶

Read the status and result ID of the SQL executed by the current identity (statement_id). Results can only be read or downloaded using this result ID if the status is success.

HTTP
POST $CLOUDSIGMA_API_BASE/query/describe

Before you call this API¶

Configure the regional API endpoint and authentication, and select the target workspace.

Request¶

Input examples

Shell
curl -X POST "$CLOUDSIGMA_API_BASE/query/describe" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d "{\"query_id\":\"$QUERY_ID\"}"

Parameter reference

Request body

Parameter	Type	Required	Description
`query_id`	string	Required	The query ID returned by [Execute SQL](execute-sql.md).

Successful response¶

statement_id is used to read or download results and cannot be replaced by query_id. When the status is success, the Statement ID can be used to obtain the result.

The response fields are as follows.

Response example

JSON
{
  "code": 200,
  "data": {
    "query_id": "query_01",
    "created_at": "2026-08-18T10:00:00Z",
    "statement_id": "statement_01",
    "db_name": "sales",
    "status": "success",
    "rows_affected": 1
  }
}

Field reference

Field	Type	Description
`code`	integer	200 on success.
`data.query_id`	string	Query ID.
`data.created_at`	string	The creation time of the execution record.
`data.statement_id`	string	Result ID; used when reading or downloading the results of this SQL.
`data.db_name`	string	The database specified during execution.
`data.status`	string	Execution status.
`data.err_msg`	string	Execution error message; only returned if there is an error message.
`data.rows_affected`	integer	Number of affected rows.

Error response¶

Response example

JSON
{"code": 404, "message": "SQL 查询不存在"}

Field reference

Field	Type	Description
`code`	string	Error code.
`msg`	string	Readable error message.
`data`	null	`null` in an error response.

Follow-up operations¶

When the status indicates success, use the returned result to identify query execution result or download execution result. Cancel execution while still executing and needs to be aborted.

Last updated on Sep 15, 2026