Query Runs

View the history of executed queries. Each query run records the SQL text, execution time, result reference, and status. Useful for auditing and debugging query performance.

List query runs

List query runs for the database named by the required X-Database-Id header.

Query parameters

• limit integer — Maximum number of results
• cursor string — Pagination cursor
• status string — Filter by status (comma-separated, e.g. status=running,failed)
• saved_query_id string — Filter by saved query ID

Headers

• X-Database-Id string — required. Database to scope the query runs to (required)

Response 200 — List of query runs

• count integer — required. Min: 0
• has_more boolean — required
• limit integer — required. Min: 0
• next_cursor string,null
• query_runs QueryRunInfo[] — required
  • bytes_scanned integer,null — Total bytes of table data read from storage to run this query. null when the query touches no table at all (for example a constant expression like SELECT 1). May be 0 when the query reads a table but not its row data — for example a row count served from table statistics.
  • completed_at string,null
  • created_at string — required
  • error_message string,null
  • execution_time_ms integer,null
  • id string — required
  • result_id string,null
  • row_count integer,null
  • rows_scanned integer,null — Total rows read from storage to run this query, before any filtering or aggregation. Distinct from row_count, which is how many rows the query returned. null when the query reads no table data from storage.
  • saved_query_id string,null
  • saved_query_version integer,null
  • server_processing_ms integer,null — Total server-side processing time for this query (milliseconds). Measured from query start to result ready. Includes SQL execution, task spawning, and result preparation. Does not include network transit. Populated for all completed query runs (sync and async).
  • snapshot_id string — required
  • sql_hash string — required
  • sql_text string — required
  • status string — required
  • trace_id string,null
  • user_public_id string,null — Who ran this query: the account id from the access token the request was made with. Use it to group a caller's query history. Requests made with a credential that identifies no account instead record an opaque user_-prefixed identifier, which is stable for that credential but cannot be resolved to an account.
  • warning_message string,null

{
  "count": 0,
  "has_more": true,
  "limit": 0,
  "next_cursor": "string",
  "query_runs": [
    {
      "bytes_scanned": 0,
      "completed_at": "2026-01-01T00:00:00Z",
      "created_at": "2026-01-01T00:00:00Z",
      "error_message": "string",
      "execution_time_ms": 0,
      "id": "string",
      "result_id": "string",
      "row_count": 0,
      "rows_scanned": 0,
      "saved_query_id": "string",
      "saved_query_version": 0,
      "server_processing_ms": 0,
      "snapshot_id": "string",
      "sql_hash": "string",
      "sql_text": "string",
      "status": "string",
      "trace_id": "string",
      "user_public_id": "string",
      "warning_message": "string"
    }
  ]
}

Errors

Get query run

Get the status and details of a specific query run by ID, scoped to the database named by the required X-Database-Id header.

Path parameters

• id string — required. Query run ID

Headers

• X-Database-Id string — required. Database the query run belongs to (required)

Response 200 — Query run details

• bytes_scanned integer,null — Total bytes of table data read from storage to run this query. null when the query touches no table at all (for example a constant expression like SELECT 1). May be 0 when the query reads a table but not its row data — for example a row count served from table statistics.
• completed_at string,null
• created_at string — required
• error_message string,null
• execution_time_ms integer,null
• id string — required
• result_id string,null
• row_count integer,null
• rows_scanned integer,null — Total rows read from storage to run this query, before any filtering or aggregation. Distinct from row_count, which is how many rows the query returned. null when the query reads no table data from storage.
• saved_query_id string,null
• saved_query_version integer,null
• server_processing_ms integer,null — Total server-side processing time for this query (milliseconds). Measured from query start to result ready. Includes SQL execution, task spawning, and result preparation. Does not include network transit. Populated for all completed query runs (sync and async).
• snapshot_id string — required
• sql_hash string — required
• sql_text string — required
• status string — required
• trace_id string,null
• user_public_id string,null — Who ran this query: the account id from the access token the request was made with. Use it to group a caller's query history. Requests made with a credential that identifies no account instead record an opaque user_-prefixed identifier, which is stable for that credential but cannot be resolved to an account.
• warning_message string,null

{
  "bytes_scanned": 0,
  "completed_at": "2026-01-01T00:00:00Z",
  "created_at": "2026-01-01T00:00:00Z",
  "error_message": "string",
  "execution_time_ms": 0,
  "id": "string",
  "result_id": "string",
  "row_count": 0,
  "rows_scanned": 0,
  "saved_query_id": "string",
  "saved_query_version": 0,
  "server_processing_ms": 0,
  "snapshot_id": "string",
  "sql_hash": "string",
  "sql_text": "string",
  "status": "string",
  "trace_id": "string",
  "user_public_id": "string",
  "warning_message": "string"
}

Errors