# Queries

## Overview

Use these API operations to interact with [Saved and Scheduled Searches](https://docs.panther.com/search/scheduled-searches) in Panther.

To call the API, see the [How to use the Panther REST API](https://docs.panther.com/panther-developer-workflows/api/rest/..#how-to-use-the-panther-rest-api) instructions—including [directions for how to invoke it directly from this documentation page](https://docs.panther.com/panther-developer-workflows/api/rest/..#step-3-invoke-the-panther-rest-api).

{% hint style="warning" %}
Queries managed via the API must be written in SQL; they cannot use [PantherFlow](https://docs.panther.com/pantherflow).
{% endhint %}

## Required permissions

* For `GET` operations, your API token must have the `Query Data Lake` permission.
* For `POST`, `PUT`, and `DELETE` operations, your API token must have the `Manage Saved Searches` permission.

## Operations

## POST /queries

> create query

```json
{"openapi":"3.0.3","info":{"title":"Panther REST API","version":"1.0"},"tags":[{"name":"query","description":"The query api handles operations for queries"}],"servers":[{"url":"https://{api_host}","variables":{"api_host":{"default":"your-api-host"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"X-API-Key","in":"header"}},"schemas":{"QueryAPI.ModifyQuery":{"type":"object","properties":{"description":{"type":"string","description":"The description of the query"},"emailConfig":{"$ref":"#/components/schemas/QueryAPI.EmailConfig"},"name":{"type":"string","description":"The name of the query"},"schedule":{"$ref":"#/components/schemas/QueryAPI.Schedule"},"sql":{"type":"string","description":"The raw sql of the query"}},"required":["sql","name"]},"QueryAPI.EmailConfig":{"type":"object","properties":{"preferAttachment":{"type":"boolean","description":"If true, prefer sending query results as attachment (if possible within 10MB limit). Otherwise results will be sent via link","default":false},"recipients":{"type":"array","items":{"type":"string"},"description":"List of email addresses to send the query results to"},"sendEmpty":{"type":"boolean","description":"If true, sends an email even if the query returned no rows","default":false}}},"QueryAPI.Schedule":{"type":"object","properties":{"cron":{"type":"string","description":"The cron expression"},"disabled":{"type":"boolean","description":"Disable the schedule"},"rateMinutes":{"type":"integer","format":"int64"},"timeoutMinutes":{"type":"integer","format":"int64"}}},"QueryAPI.Query":{"type":"object","properties":{"createdAt":{"type":"string"},"description":{"type":"string","description":"The description of the query"},"emailConfig":{"$ref":"#/components/schemas/QueryAPI.EmailConfig"},"id":{"type":"string","description":"The generated ID of the query"},"managed":{"type":"boolean","description":"Determines if the query is managed by panther"},"name":{"type":"string","description":"The name of the query"},"schedule":{"$ref":"#/components/schemas/QueryAPI.Schedule"},"sql":{"type":"string","description":"The raw sql of the query"},"updatedAt":{"type":"string"}}},"QueryAPI.BadRequestError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"QueryAPI.ExistsError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"paths":{"/queries":{"post":{"tags":["query"],"summary":"create query","operationId":"query#create","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryAPI.ModifyQuery"}}}},"responses":{"200":{"description":"OK response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryAPI.Query"}}}},"400":{"description":"bad_request: Bad Request response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryAPI.BadRequestError"}}}},"409":{"description":"exists: Conflict response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryAPI.ExistsError"}}}}}}}}}
```

## GET /queries/{id}

> get query

```json
{"openapi":"3.0.3","info":{"title":"Panther REST API","version":"1.0"},"tags":[{"name":"query","description":"The query api handles operations for queries"}],"servers":[{"url":"https://{api_host}","variables":{"api_host":{"default":"your-api-host"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"X-API-Key","in":"header"}},"schemas":{"QueryAPI.Query":{"type":"object","properties":{"createdAt":{"type":"string"},"description":{"type":"string","description":"The description of the query"},"emailConfig":{"$ref":"#/components/schemas/QueryAPI.EmailConfig"},"id":{"type":"string","description":"The generated ID of the query"},"managed":{"type":"boolean","description":"Determines if the query is managed by panther"},"name":{"type":"string","description":"The name of the query"},"schedule":{"$ref":"#/components/schemas/QueryAPI.Schedule"},"sql":{"type":"string","description":"The raw sql of the query"},"updatedAt":{"type":"string"}}},"QueryAPI.EmailConfig":{"type":"object","properties":{"preferAttachment":{"type":"boolean","description":"If true, prefer sending query results as attachment (if possible within 10MB limit). Otherwise results will be sent via link","default":false},"recipients":{"type":"array","items":{"type":"string"},"description":"List of email addresses to send the query results to"},"sendEmpty":{"type":"boolean","description":"If true, sends an email even if the query returned no rows","default":false}}},"QueryAPI.Schedule":{"type":"object","properties":{"cron":{"type":"string","description":"The cron expression"},"disabled":{"type":"boolean","description":"Disable the schedule"},"rateMinutes":{"type":"integer","format":"int64"},"timeoutMinutes":{"type":"integer","format":"int64"}}},"QueryAPI.NotFoundError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"paths":{"/queries/{id}":{"get":{"tags":["query"],"summary":"get query","operationId":"query#get","parameters":[{"name":"id","in":"path","description":"ID of the query to fetch","required":true,"schema":{"type":"string","description":"ID of the query to fetch"}}],"responses":{"200":{"description":"OK response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryAPI.Query"}}}},"404":{"description":"not_found: Not Found response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryAPI.NotFoundError"}}}}}}}}}
```

## update query

> updates a query

```json
{"openapi":"3.0.3","info":{"title":"Panther REST API","version":"1.0"},"tags":[{"name":"query","description":"The query api handles operations for queries"}],"servers":[{"url":"https://{api_host}","variables":{"api_host":{"default":"your-api-host"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"X-API-Key","in":"header"}},"schemas":{"QueryAPI.ModifyQuery":{"type":"object","properties":{"description":{"type":"string","description":"The description of the query"},"emailConfig":{"$ref":"#/components/schemas/QueryAPI.EmailConfig"},"name":{"type":"string","description":"The name of the query"},"schedule":{"$ref":"#/components/schemas/QueryAPI.Schedule"},"sql":{"type":"string","description":"The raw sql of the query"}},"required":["sql","name"]},"QueryAPI.EmailConfig":{"type":"object","properties":{"preferAttachment":{"type":"boolean","description":"If true, prefer sending query results as attachment (if possible within 10MB limit). Otherwise results will be sent via link","default":false},"recipients":{"type":"array","items":{"type":"string"},"description":"List of email addresses to send the query results to"},"sendEmpty":{"type":"boolean","description":"If true, sends an email even if the query returned no rows","default":false}}},"QueryAPI.Schedule":{"type":"object","properties":{"cron":{"type":"string","description":"The cron expression"},"disabled":{"type":"boolean","description":"Disable the schedule"},"rateMinutes":{"type":"integer","format":"int64"},"timeoutMinutes":{"type":"integer","format":"int64"}}},"QueryAPI.Query":{"type":"object","properties":{"createdAt":{"type":"string"},"description":{"type":"string","description":"The description of the query"},"emailConfig":{"$ref":"#/components/schemas/QueryAPI.EmailConfig"},"id":{"type":"string","description":"The generated ID of the query"},"managed":{"type":"boolean","description":"Determines if the query is managed by panther"},"name":{"type":"string","description":"The name of the query"},"schedule":{"$ref":"#/components/schemas/QueryAPI.Schedule"},"sql":{"type":"string","description":"The raw sql of the query"},"updatedAt":{"type":"string"}}},"QueryAPI.BadRequestError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"QueryAPI.NotFoundError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"paths":{"/queries/{id}":{"post":{"tags":["query"],"summary":"update query","description":"updates a query","operationId":"query#update","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryAPI.ModifyQuery"}}}},"responses":{"200":{"description":"OK response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryAPI.Query"}}}},"400":{"description":"bad_request: Bad Request response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryAPI.BadRequestError"}}}},"404":{"description":"not_found: Not Found response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryAPI.NotFoundError"}}}}}}}}}
```

## DELETE /queries/{id}

> delete query

```json
{"openapi":"3.0.3","info":{"title":"Panther REST API","version":"1.0"},"tags":[{"name":"query","description":"The query api handles operations for queries"}],"servers":[{"url":"https://{api_host}","variables":{"api_host":{"default":"your-api-host"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"X-API-Key","in":"header"}},"schemas":{"QueryAPI.BadRequestError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"QueryAPI.NotFoundError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"paths":{"/queries/{id}":{"delete":{"tags":["query"],"summary":"delete query","operationId":"query#delete","parameters":[{"name":"id","in":"path","description":"ID of the query to delete","required":true,"schema":{"type":"string","description":"ID of the query to delete"}}],"responses":{"204":{"description":"No Content response."},"400":{"description":"bad_request: Bad Request response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryAPI.BadRequestError"}}}},"404":{"description":"not_found: Not Found response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryAPI.NotFoundError"}}}}}}}}}
```

## GET /queries

> list queries

```json
{"openapi":"3.0.3","info":{"title":"Panther REST API","version":"1.0"},"tags":[{"name":"query","description":"The query api handles operations for queries"}],"servers":[{"url":"https://{api_host}","variables":{"api_host":{"default":"your-api-host"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"X-API-Key","in":"header"}},"schemas":{"QueryAPI.ListResp":{"type":"object","properties":{"next":{"type":"string","description":"Pagination token for the next page of results"},"results":{"type":"array","items":{"$ref":"#/components/schemas/QueryAPI.Query"}}}},"QueryAPI.Query":{"type":"object","properties":{"createdAt":{"type":"string"},"description":{"type":"string","description":"The description of the query"},"emailConfig":{"$ref":"#/components/schemas/QueryAPI.EmailConfig"},"id":{"type":"string","description":"The generated ID of the query"},"managed":{"type":"boolean","description":"Determines if the query is managed by panther"},"name":{"type":"string","description":"The name of the query"},"schedule":{"$ref":"#/components/schemas/QueryAPI.Schedule"},"sql":{"type":"string","description":"The raw sql of the query"},"updatedAt":{"type":"string"}}},"QueryAPI.EmailConfig":{"type":"object","properties":{"preferAttachment":{"type":"boolean","description":"If true, prefer sending query results as attachment (if possible within 10MB limit). Otherwise results will be sent via link","default":false},"recipients":{"type":"array","items":{"type":"string"},"description":"List of email addresses to send the query results to"},"sendEmpty":{"type":"boolean","description":"If true, sends an email even if the query returned no rows","default":false}}},"QueryAPI.Schedule":{"type":"object","properties":{"cron":{"type":"string","description":"The cron expression"},"disabled":{"type":"boolean","description":"Disable the schedule"},"rateMinutes":{"type":"integer","format":"int64"},"timeoutMinutes":{"type":"integer","format":"int64"}}}}},"paths":{"/queries":{"get":{"tags":["query"],"summary":"list queries","operationId":"query#list","parameters":[{"name":"cursor","in":"query","description":"the pagination token","allowEmptyValue":true,"schema":{"type":"string","description":"the pagination token"}},{"name":"limit","in":"query","description":"the maximum results to return","allowEmptyValue":true,"schema":{"type":"integer","description":"the maximum results to return","default":100,"format":"int64"}}],"responses":{"200":{"description":"OK response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryAPI.ListResp"}}}}}}}}}
```