> For the complete documentation index, see [llms.txt](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/listassessmentqueries.md). # List saved queries List Veza-created and user-created saved queries, with filters, ordering, and optional results and risk statistics. Returns the Veza-created and user-created saved queries that you can see, on one page or in pages of `page_size`. Use it to get a query's ID, to search queries by name, label, integration, or risk level, or to read each query's latest result. To get one query by ID, use [Get a saved query](/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/getassessmentquery.md). In Veza, saved queries are listed on the [Saved Queries](/4yItIzMvkpAvMVFAamTf/features/search/saved-queries.md) page. ## Endpoint ```sh GET /api/v1/assessments/queries ``` This endpoint requires one of these built-in [roles](/4yItIzMvkpAvMVFAamTf/administration/administration/users/roles.md): **Administrator**, **Operator**, **Access Reviews Admin**, **Viewer**, **NHI Security Admin**, **Dashboard Viewer**, or **Remediation Owner**. Requests from other roles return `PermissionDenied`. {% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/v1/assessments/queries" method="get" %} [openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-7dd8f2774730d4d5e763f90390027ed45ec60546%2Fopenapi.yaml?alt=media) {% endopenapi %} ## Request Send every parameter in the query string, URL-encoded. All parameters are optional. For how paging works across Veza APIs, see [Pagination](/4yItIzMvkpAvMVFAamTf/developers/api/pagination.md). These parameters choose which queries are returned: | Field | Type | Required? | Description | | -------------------------- | ------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `filter` | string | No | A filter expression on query fields, such as `name co "S3"` or `disabled eq true`. See [Filter and order fields](#filter-and-order-fields). | | `include_inactive_queries` | boolean | No | When `true`, also returns queries that the integration rule omits, and lists every integration in each query's `integration_types`. See [Default results](#default-results). | | `risks_only` | boolean | No | When `true`, returns only queries with a risk level other than `NONE`. | | `violations_only` | boolean | No | Deprecated; use `risks_only`. | | `rules_filter` | enum | No | Filters by whether any rule is attached: `ALL_QUERIES` (default), `QUERIES_WITH_RULES`, or `QUERIES_WITHOUT_RULES`. | | `action_filter` | enum | No | Filters by whether a rule with an action is attached: `ALL_QUERIES_ACTION` (default), `QUERIES_WITH_ACTIONS`, or `QUERIES_WITHOUT_ACTIONS`. | | `query_variant_filter` | enum | No | Filters by query shape: `ALL` (default); `PATH`, queries with at least one destination type in a relationship; or `PATH_WITH_SUMMARY`, queries with path summary entity types. | These parameters set the order and paging: | Field | Type | Required? | Description | | ------------ | ------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `order_by` | string | No | Up to two fields, comma-separated, each optionally followed by `asc` (default) or `desc`. Without `order_by`, results are ordered by name, except with a `name co` filter (see [Filter and order fields](#filter-and-order-fields)). | | `page_size` | integer | No | Maximum number of queries on a page. When omitted or `0`, all matching queries are returned on one page. A page can hold fewer queries even when more pages exist. | | `page_token` | string | No | The `next_page_token` from the previous page. | These parameters add fields to each returned query: | Field | Type | Required? | Description | | -------------------------- | ------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `include_results` | boolean | No | When `true`, populates the latest `result`, `result_evaluated_at`, `result_evaluated`, and `approx_total_source_nodes_count`. | | `include_risk_statistics` | boolean | No | When `true`, populates `risk_statistics` (affected and suppressed entity counts, last occurrence, and status) on queries with a risk level other than `NONE`. | | `include_has_action` | boolean | No | When `true`, populates `has_action`: whether the query has at least one [rule](/4yItIzMvkpAvMVFAamTf/features/insights/rules-and-alerts.md) with an action attached, such as **Send Alert** or **Create Review**. When omitted, `has_action` is `null` ("not computed"), not `false`. | | `include_user_details` | boolean | No | When `true`, populates `created_by_user` and `updated_by_user` with each user's ID, name, and email. Both stay `null` when no user matches, such as on Veza-created queries, whose `created_by` is `system`. | | `include_natural_language` | boolean | No | When `true`, populates `natural_language` with a plain-language description of each query. | ### Filter and order fields `filter` and `order_by` both accept `id`, `name`, `query_type`, `created_by`, `visibility`, `owners`, `integration_types`, `labels`, `created_at`, `updated_at`, `source_type`, `destination_types`, `analysis_type`, and `risk_level`. `filter` also accepts `disabled`, and `order_by` also accepts `affected_node_count` and `suppressed_node_count`. Each field supports these `filter` operators: * `name`: `eq` and `co` (contains), case-insensitive. When `order_by` isn't set, a `name co` filter returns the closest name matches first. * `owners`, `integration_types`, `labels`, and `destination_types`: `co`. * `created_at` and `updated_at`: `gt` and `lt`. * `risk_level` and `disabled`: `eq` and `ne`. * Every other field: `eq`. Join conditions with `and` or `or`, and enclose string values in double quotes. After the `order_by` fields, results are ordered by `id`, so paging is stable. ## Default results A call with no parameters returns all matching queries on one page, ordered by name. Three rules decide which queries match, and only the second can be changed by a parameter: * **Visibility:** you see your team's public queries, plus private queries that you created or own ([Query visibility and team scope](/4yItIzMvkpAvMVFAamTf/administration/administration/users/roles.md#query-visibility-and-team-scope)). This applies to every role; an Administrator can still get another user's private query by ID with [Get a saved query](/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/getassessmentquery.md). * **Integration not configured:** a query is omitted when an entity type it uses, or the identity provider it requires, has no configured integration on the tenant. A Veza-created query is also omitted when a relationship it depends on, such as an identity mapping, doesn't exist. * **Activity Monitoring:** queries that filter on activity data are returned only when [Activity Monitoring](/4yItIzMvkpAvMVFAamTf/features/activity-monitoring.md#access-monitoring-using-query-builder) is enabled on the tenant. Setting `include_inactive_queries` to `true` changes two things: it returns the queries that the integration rule omits, both kinds, and it lists every integration a query uses in `integration_types`, not only the integrations the tenant has configured. It doesn't change the visibility or Activity Monitoring rules. [Disabled queries](/4yItIzMvkpAvMVFAamTf/features/search/saved-queries.md#disable-and-enable-queries) **are** returned. To list only disabled queries, set `filter` to `disabled eq true`. ## Examples Set `VEZA_URL` and `VEZA_TOKEN` as described in [API tokens](/4yItIzMvkpAvMVFAamTf/developers/api/authentication/api-tokens.md). The `-G` and `--data-urlencode` options build and encode the query string. List queries whose names contain "S3", with their latest results. `page_size=1` keeps the sample response short: ```bash curl -X GET -G "$VEZA_URL/api/v1/assessments/queries" \ -H "Authorization: Bearer $VEZA_TOKEN" \ --data-urlencode 'filter=name co "S3"' \ --data-urlencode 'include_results=true' \ --data-urlencode 'page_size=1' ``` Example response, captured from a tenant and anonymized. The query is shortened; for the fields of a saved query, see [Query Builder parameters](/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/parameters.md). ```json { "values": [ { "id": "", "name": "All S3 buckets", "description": "Inventory of all S3 buckets in the environment.", "result_type": "NUMBER", "query_type": "SOURCE_TO_DESTINATION", "source_node_types": { "nodes": [{ "node_type": "S3Bucket", "tags": [], "conditions": [] }], "nodes_operator": "AND" }, "relates_to_exp": { "specs": [], "child_expressions": [], "operator": "AND", "not": false, "and_op_type": "INFERRED" }, "node_relationship_type": "EFFECTIVE_ACCESS", "created_by": "", "visibility": "PUBLIC", "owners": [""], "integration_types": ["aws"], "labels": ["s3", "aws", "inventory"], "created_at": "2026-04-09T16:42:42.570365112Z", "updated_at": "2026-04-21T12:48:58.173538759Z", "source_type": "S3Bucket", "destination_types": [], "risk_level": "NONE", "result": 173, "result_evaluated_at": "2026-10-21T21:55:29Z", "result_evaluated": true, "risk_statistics": null, "created_by_user": null, "updated_by_user": null, "disabled": false, "has_action": null, "edited": false } ], "next_page_token": "", "has_more": true } ``` List only disabled queries, including queries for integrations the tenant hasn't configured: ```bash curl -X GET -G "$VEZA_URL/api/v1/assessments/queries" \ -H "Authorization: Bearer $VEZA_TOKEN" \ --data-urlencode 'filter=disabled eq true' \ --data-urlencode 'include_inactive_queries=true' \ --data-urlencode 'page_size=100' ``` ## Errors and limits The requests in the following table return `InvalidArgument` (HTTP 400), with the reason in `details[].field_violations`: | Field | Cause | Message | | ---------- | --------------------------------------- | --------------------------------------------------------------------- | | `filter` | A field that the filter doesn't support | `Unsupported filter attribute []. Supported attributes: [...]` | | `order_by` | More than two fields | `Too many fields specified. The maximum is 2.` | For shared status codes and the error body, see [Troubleshooting](/4yItIzMvkpAvMVFAamTf/developers/api/errors.md). To create, change, or delete a saved query, see [Save a query](/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/createassessmentquery.md), [Update a query](/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/updateassessmentquery.md), and [Delete a query](/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/deleteassessmentquery.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/listassessmentqueries.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.