# Query Runs

Source: https://www.hotdata.dev/docs/api-reference/query-runs
Site index: https://www.hotdata.dev/llms.txt

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

`GET /v1/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`

```json
{
  "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**

| Status | Description |
| ------ | ----------- |
| `400` | Missing or malformed X-Database-Id header |
| `404` | Database not found |

## Get query run

`GET /v1/query-runs/{id}`

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`

```json
{
  "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**

| Status | Description |
| ------ | ----------- |
| `400` | Missing or malformed X-Database-Id header |
| `404` | Query run or database not found |