> 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/getassessmentqueryspecnodes.md). # Get query spec nodes Run a query spec and page through the matching entities without computing a total count. Runs a query spec and returns the matching source entities with their details, one page at a time, without computing a result count. It can be faster than [Get query spec results](/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/getassessmentqueryspecresult.md) for complex queries when the total isn't needed. To list the destination entities for one result, use [Get query spec node destinations](/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/getassessmentqueryspecdestinationnodes.md). ## Endpoint ```sh POST /api/v1/assessments/query_spec:nodes ``` 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/query\_spec:nodes" method="post" %} [openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-52896198b0199515de31fd5ac6c2094ad6ea5bf1%2Fopenapi.yaml?alt=media) {% endopenapi %} ## Request The request body **is** the query spec, with its fields at the top level. Don't wrap it in a `spec` or `body` object. For every spec field, see [Query Builder Parameters](/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/parameters.md); use `relates_to_exp` for destination, permission, and relationship constraints. Paging and ordering go in the query string: | Field | Type | Required? | Description | | ---------------------------------- | --------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `page_size` | integer (query) | No | Maximum number of results on a page, up to 10,000. A page can hold fewer results even when more pages exist. | | `page_token` | string (query) | No | The `next_page_token` from the previous page, URL-encoded. | | `order_by` | string (query) | No | Orders source entities by `destination_node_count`, `destination_node_percentage_of_total`, or `risk_score`, followed by `ASC` or `DESC`. | | `apply_risk_suppressed_constraint` | boolean (query) | No | When `true`, applies `risk_suppressed_constraints`. | | `risk_suppressed_constraints` | object (query) | No | The constraints to apply when `apply_risk_suppressed_constraint` is `true`. See [RiskSuppressedConstraintsCollection](/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/parameters.md#risksuppressedconstraintscollection). | | `add_access_stats` | boolean (query) | No | When `true`, adds access statistics where available. | | `skip_single_entity_access_stats` | boolean (query) | No | When `true`, skips per-entity access statistics such as last-used time, which can make the call faster. | Set `page_size` and `page_token` in the query string. The same names inside the query spec body don't page this endpoint. For how paging works across Veza APIs, including why to rely on `has_more`, see [Pagination](/4yItIzMvkpAvMVFAamTf/developers/api/pagination.md). ## Examples Set `VEZA_URL` and `VEZA_TOKEN` as described in [API tokens](/4yItIzMvkpAvMVFAamTf/developers/api/authentication/api-tokens.md). Find AWS IAM users with the raw permission to change S3 bucket ACLs, 10 results per page: ```bash curl -X POST "$VEZA_URL/api/v1/assessments/query_spec:nodes?page_size=10" \ -H "Authorization: Bearer $VEZA_TOKEN" \ -H "Content-Type: application/json" \ --data '{ "query_type": "SOURCE_TO_DESTINATION", "node_relationship_type": "EFFECTIVE_ACCESS", "source_node_types": { "nodes": [{ "node_type": "AwsIamUser" }] }, "relates_to_exp": { "specs": [ { "node_types": { "nodes": [{ "node_type": "S3Bucket" }] }, "raw_permissions": { "operator": "OR", "values": ["s3:PutBucketAcl"] } } ] } }' ``` Example response (constructed from `AssessmentQueryNodesResponse`; entity properties vary by type and are shortened here): ```json { "values": [ { "id": "arn:aws:iam::123456789012:user/jdoe", "type": "AwsIamUser", "properties": { "aws_account_id": "123456789012", "name": "jdoe", "provider_id": "123456789012" }, "destination_node_count": 25, "permissions": [], "engagement_access_stats": null, "access_stats": null, "destination_node_ids": [], "risk_level": "NONE", "raw_permissions": [], "effective_permissions": [], "unsupported_conditions": {}, "destination_node_percentage_of_total": 0, "tags": [], "specified_tags": [], "filtered_raw_permissions": [], "corresponding_effective_permissions": [], "single_entity_access_stats": null, "additional_node_properties": null, "integration_type": "aws", "joined_nodes": {}, "additional_spec_properties": null } ], "path_values": [], "next_page_token": "", "has_more": true } ``` `permissions` and `destination_node_ids` are deprecated; don't rely on them. ## Errors and limits A `page_size` greater than 10,000 returns `InvalidArgument` (HTTP 400) with the description `Must be less than or equal to 10000: GetAssessmentQuerySpecNodes` on `page_size`. For shared status codes and the error body, see [Troubleshooting](/4yItIzMvkpAvMVFAamTf/developers/api/errors.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/getassessmentqueryspecnodes.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.