# 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"}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.panther.com/panther-developer-workflows/api/rest/queries.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.