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 — Bytes this query actually fetched from storage. Not a measure of how much data the query covered — it counts the reads that reached storage, so the same SQL over the same rows reports a different number depending on what was already cached. null means the query touched no table at all (for example a constant expression like SELECT 1). 0 means the query read a table but fetched nothing from storage. It is a normal, common answer, not an error or a missing measurement, and it does not mean the query did no work — rows_scanned shows the rows it went through. The usual cause is a warm cache: re-running a query whose data or file metadata is already held in memory reports far fewer bytes than the first run, frequently 0, with rows_scanned unchanged. A query answered from table statistics alone (a row count, say) also reports 0. Because of this, bytes_scanned is not a proxy for query cost or query volume. GET /v1/usage sums this field over a period, so that total is the storage read a workspace caused, not the work its queries did: repeating one query cheaply adds little or nothing to it.
  • 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 — Bytes this query actually fetched from storage. Not a measure of how much data the query covered — it counts the reads that reached storage, so the same SQL over the same rows reports a different number depending on what was already cached. null means the query touched no table at all (for example a constant expression like SELECT 1). 0 means the query read a table but fetched nothing from storage. It is a normal, common answer, not an error or a missing measurement, and it does not mean the query did no work — rows_scanned shows the rows it went through. The usual cause is a warm cache: re-running a query whose data or file metadata is already held in memory reports far fewer bytes than the first run, frequently 0, with rows_scanned unchanged. A query answered from table statistics alone (a row count, say) also reports 0. Because of this, bytes_scanned is not a proxy for query cost or query volume. GET /v1/usage sums this field over a period, so that total is the storage read a workspace caused, not the work its queries did: repeating one query cheaply adds little or nothing to it.
• 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