> ## Documentation Index
> Fetch the complete documentation index at: https://docs.endorlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.endorlabs.com/feedback

```json
{
  "path": "/developers-api/rest-api/using-the-rest-api/advanced-use-cases/saved-queries/index",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Using saved queries

> Learn how to use saved queries for interacting with the Endor Labs REST API.

The Endor Labs REST API provides the [Query Service](/api-reference/queryservice/createquery) for flexible requests for resources. The Endor Labs REST API also provides the ability to save and manage queries for your own use cases through the [Saved Query Service](/api-reference/savedqueryservice/listsavedqueries).

See [Using the Query Service](/developers-api/rest-api/using-the-rest-api/advanced-use-cases/query-service) for examples on using the Query Service to specify and request resources from the Endor Labs REST API.

## Creating a saved query

To create a saved query, embed a Query object specifying the request in a SavedQuery object.

<Tabs>
  <Tab title="endorctl">
    ```bash theme={null}
    saved_query_data=$(cat << EOF
    {
      "meta": {
        "name": "Saved Query for Recent Vulnerabilities"
      },
      "spec": {
        "query": {
          "meta": {
            "name": "Query for Recent Vulnerabilities"
          },
          "spec": {
            "query_spec": {
              "kind": "Finding",
              "list_parameters": {
                "filter": "meta.create_time > now(-24h) and spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY]",
                "mask": "uuid,meta.create_time,meta.update_time,meta.description,spec.level"
              }
            }
          },
          "tenant_meta": {
            "namespace": "$ENDOR_NAMESPACE"
          }
        }
      }
    }
    EOF
    )

    endorctl api create --resource SavedQuery \
      --data "$saved_query_data"
    ```
  </Tab>

  <Tab title="curl">
    ```bash theme={null}
    saved_query_data=$(cat << EOF
    {
      "meta": {
        "name": "Saved Query for Recent Vulnerabilities"
      },
      "spec": {
        "query": {
          "meta": {
            "name": "Query for Recent Vulnerabilities"
          },
          "spec": {
            "query_spec": {
              "kind": "Finding",
              "list_parameters": {
                "filter": "meta.create_time > now(-24h) and spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY]",
                "mask": "uuid,meta.create_time,meta.update_time,meta.description,spec.level"
              }
            }
          },
          "tenant_meta": {
            "namespace": "$ENDOR_NAMESPACE"
          }
        }
      },
      "tenant_meta": {
        "namespace": "$ENDOR_NAMESPACE"
      }
    }
    EOF
    )

    curl "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/saved-queries" \
      --header "Authorization: Bearer $ENDOR_TOKEN" \
      --request POST \
      --data "$saved_query_data"
    ```
  </Tab>

  <Tab title="HTTP">
    ```bash theme={null}
    @baseUrl = https://api.endorlabs.com
    @token = `<insert-access-token>`
    @namespace = `<insert-namespace>`

    ###
    POST {{baseUrl}}/v1/namespaces/{{namespace}}/saved-queries HTTP/1.1
    Authorization: Bearer {{token}}

    {
      "meta": {
        "name": "Saved Query for Recent Vulnerabilities"
      },
      "spec": {
        "query": {
          "meta": {
            "name": "Query for Recent Vulnerabilities"
          },
          "spec": {
            "query_spec": {
              "kind": "Finding",
              "list_parameters": {
                "filter": "meta.create_time > now(-24h) and spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY]",
                "mask": "uuid,meta.create_time,meta.update_time,meta.description,spec.level"
              }
            }
          },
          "tenant_meta": {
            "namespace": "{{namespace}}"
          }
        }
      },
      "tenant_meta": {
        "namespace": "{{namespace}}"
      }
    }
    ```
  </Tab>
</Tabs>

## Updating a saved query

The following example updates the Query specified in the SavedQuery to add additional [list parameters](/developers-api/rest-api/using-the-rest-api/getting-started#list-parameters).

<Tabs>
  <Tab title="endorctl">
    ```bash theme={null}
    saved_query_uuid="`<insert-uuid>`"
    saved_query_data=$(cat << EOF
    {
      "spec": {
        "query": {
          "spec": {
            "query_spec": {
              "kind": "Finding",
              "list_parameters": {
                "filter": "meta.create_time > now(-24h) and spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY]",
                "mask": "uuid,meta.create_time,meta.update_time,meta.description,spec.level",
                "page_size": 10,
                "sort": {
                  "order": "SORT_ENTRY_ORDER_DESC",
                  "path": "meta.create_time"
                }
              }
            }
          }
        }
      }
    }
    EOF
    )

    endorctl api update --resource SavedQuery \
      --uuid "$saved_query_uuid" \
      --field-mask "spec.query.spec.query_spec" \
      --data "$saved_query_data"
    ```
  </Tab>

  <Tab title="curl">
    ```bash theme={null}
    saved_query_uuid="`<insert-uuid>`"
    saved_query_data=$(cat << EOF
    {
      "request": {
        "update_mask": "spec.query.spec.query_spec"
      },
      "object": {
        "uuid": "$saved_query_uuid",
        "spec": {
          "query": {
            "spec": {
              "query_spec": {
                "kind": "Finding",
                "list_parameters": {
                  "filter": "meta.create_time > now(-24h) and spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY]",
                  "mask": "uuid,meta.create_time,meta.update_time,meta.description,spec.level",
                  "page_size": 10,
                  "sort": {
                    "order": "SORT_ENTRY_ORDER_DESC",
                    "path": "meta.create_time"
                  }
                }
              }
            }
          }
        }
      }
    }
    EOF
    )

    curl "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/saved-queries" \
      --header "Authorization: Bearer $ENDOR_TOKEN" \
      --request PATCH \
      --data "$saved_query_data"
    ```
  </Tab>

  <Tab title="HTTP">
    ```bash theme={null}
    @baseUrl = https://api.endorlabs.com
    @token = `<insert-access-token>`
    @namespace = `<insert-namespace>`
    @uuid = `<insert-uuid>`

    ###
    PATCH {{baseUrl}}/v1/namespaces/{{namespace}}/saved-queries HTTP/1.1
    Authorization: Bearer {{token}}

    {
      "request": {
        "update_mask": "spec.query.spec.query_spec"
      },
      "object": {
        "uuid": "{{uuid}}",
        "spec": {
          "query": {
            "spec": {
              "query_spec": {
                "kind": "Finding",
                "list_parameters": {
                  "filter": "meta.create_time > now(-24h) and spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY]",
                  "mask": "uuid,meta.create_time,meta.update_time,meta.description,spec.level",
                  "page_size": 10,
                  "sort": {
                    "order": "SORT_ENTRY_ORDER_DESC",
                    "path": "meta.create_time"
                  }
                }
              }
            }
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

See also [interactive mode](/developers-api/cli/commands/api#endorctl-api-update-interactive-mode) for managing updates to a SavedQuery with `endorctl api update`:

```bash theme={null}
endorctl api update --interactive --resource SavedQuery \
  --name "Saved Query for Recent Vulnerabilities"
```

## Evaluating saved queries

After you create a Saved Query, you can evaluate the request specified by its Query on demand.

<Tabs>
  <Tab title="endorctl">
    ```bash theme={null}
    endorctl api get --resource SavedQuery --uuid `<insert-uuid>`
    ```
  </Tab>

  <Tab title="curl">
    ```bash theme={null}
    base_url="https://api.endorlabs.com"
    uuid="`<insert-uuid>`"

    curl "$base_url/v1/namespaces/$ENDOR_NAMESPACE/saved-queries/$uuid/evaluate" \
      --header "Authorization: Bearer $ENDOR_TOKEN"
    ```
  </Tab>

  <Tab title="HTTP">
    ```bash theme={null}
    @baseUrl = https://api.endorlabs.com
    @token = `<insert-access-token>`
    @namespace = `<insert-namespace>`
    @uuid = `<insert-uuid>`

    ###
    GET {{baseUrl}}/v1/namespaces/{{namespace}}/saved-queries/{{uuid}}/evaluate HTTP/1.1
    Authorization: Bearer {{token}}
    ```
  </Tab>
</Tabs>

The response returns the resulting data in a nested field under the Query specification. Use the `jq` command to extract the nested data.

For the example queries given above, the following command will evaluate the given saved query, and extract the list of Finding objects from the Query response:

```bash theme={null}
endorctl api get --resource SavedQuery --uuid <insert-uuid> \
  | jq '.spec.query.spec.query_response.list.objects[]'
```