# List

Launch stage: GA

`GET /api/2.0/sql/history/queries`

List the history of queries through SQL warehouses, and serverless compute.

 You can filter by user ID, warehouse ID, status, and time range.
 Most recently started queries are returned first (up to max_results in request).
 The pagination token returned in response can be used to list subsequent query statuses.

API scopes: query-history

## Query parameters

- `filter_by` (object, optional)
  An optional filter object to limit query history results. Accepts parameters such as user IDs, endpoint IDs, and statuses to narrow the returned data.
   In a URL, the parameters of this filter are specified with dot notation. For example: `filter_by.statement_ids`.
  - `query_start_time_range` (object, optional)
    A range filter for query submitted time. The time range must be less than or equal to 30 days.
    - `start_time_ms` (int64, optional)
      The start time in milliseconds.
    - `end_time_ms` (int64, optional)
      The end time in milliseconds.
  - `user_ids` (array of int64, optional)
    A list of user IDs who ran the queries.
    Example: `1234567890123456`
  - `statuses` (array of string, optional)
    A list of statuses (QUEUED, RUNNING, CANCELED, FAILED, FINISHED) to match query results. Corresponds to
     the `status` field in the response.
     Filtering for multiple statuses is not recommended. Instead, opt to filter by a single status
     multiple times and then combine the results.
    Possible values: `QUEUED`, `STARTED`, `COMPILING`, `COMPILED`, `RUNNING`, `CANCELED`, `FAILED`, `FINISHED`
    Example: `FINISHED`
  - `warehouse_ids` (array of string, optional)
    A list of warehouse IDs.
    Example: `098765321fedcba`
  - `statement_ids` (array of string, optional)
    A list of statement IDs.
    Example: `556c0261-147b-4698-9d66-fdb852f3e94e`
- `max_results` (int32, optional)
  Limit the number of results returned in one page. Must be less than 1000 and the default is 100.
  Default: `100`
- `page_token` (string, optional)
  A token that can be used to get the next page of results. The token can contains characters that need to be encoded before using it in a URL.
   For example, the character '+' needs to be replaced by %2B. This field is optional.
- `include_metrics` (boolean, optional)
  Whether to include the query metrics with each query.
   Only use this for a small subset of queries (max_results).
   Defaults to false.

## Returns

Returns a list of QueryInfo objects.

## Response

```json
{
  "next_page_token": "Ci0KJDU4NjEwZjY5LTgzNzUtNDdiMS04YTg1LWYxNTU5ODI5MDYyMhDdobu",
  "has_next_page": true,
  "res": [
    {
      "query_id": "f996b47c-6672-4763-9668-d491a82099f5",
      "status": "FINISHED",
      "query_text": "SELECT * FROM customers;",
      "query_start_time_ms": 1595357086200,
      "execution_end_time_ms": 1595357086373,
      "query_end_time_ms": 1595357087200,
      "user_id": 1234567890123456,
      "user_name": "user@example.com",
      "spark_ui_url": "https://\u003cdatabricks-instance\u003e/sparkui/1234-567890-test123/driver-1234567890123456789/SQL/execution/?id=0",
      "endpoint_id": "string",
      "rows_produced": 100,
      "error_message": "Table or view not found: customers; line 1 pos 14;\n'GlobalLimit 1000\n+- 'LocalLimit 1000\n +- 'Project [*]\n +- 'UnresolvedRelation [sales]\n",
      "lookup_key": "CiQ3OGFkYmQ2Zi00ZGUwLTRlNTYtOTkxZC05Y2I5OTNlZTViYjcQ4N6r/dguGhBlM2VlYTVlOTExMjFkMzNjILPbh9OK6uoL",
      "metrics": {},
      "executed_as_user_id": 0,
      "executed_as_user_name": "string",
      "session_id": "f996b47c-6672-4763-9668-d491a82099f5",
      "is_final": true,
      "channel_used": {},
      "plans_state": "EXISTS",
      "statement_type": "SELECT",
      "warehouse_id": "098765321fedcba",
      "duration": 1000,
      "client_application": "Power BI",
      "query_source": {},
      "cache_query_id": "f996b47c-6672-4763-9668-d491a82099f5",
      "query_tags": [
        {}
      ]
    }
  ]
}
```