Get query spec nodes

GetAssessmentQuerySpecNodes returns the entity details for nodes in the query without generating a result count. This option uses pagination and can be faster for complex queries where the total number of search results is not needed.

The request must include the full query spec object and the source_node_id of the query result to retrieve destination nodes for. Additionally, providing a snapshot_id will return destination nodes based on a Time Machine snapshot.

When specifying a page_size in the query string, responses will include the next_page_token and indicate has_more if additional results are available. Note that a page can be empty even when more results exist.

post

Authorizations

Query parameters

page_sizeanyoptional

The maximum number of results to be returned. Fewer results may be returned even when more pages exist.

page_tokenanyoptional

The token specifying the specific page of results to retrieve.

order_byanyoptional

Valid ordering options are destination_node_count ASC/DESC and risk_score ASC/DESC. Note: These options are used for ordering source nodes only.

Body

query_typestring · enum · default: "SYSTEM_CREATED"optional

Options: SYSTEM_CREATED, SOURCE_TO_DESTINATION, DESTINATION_NODES

source_node_typesobjectoptional

destination_node_typesobjectoptional

required_intermediate_node_typesobjectoptional

avoided_intermediate_node_typesobjectoptional

raw_permissionsobjectoptional

effective_permissionsobjectoptional

customized_variablesobject[]optional

no_relationbooleanoptional

snapshot_idstring · uint64optional

node_relationship_typestring · enum · default: "EFFECTIVE_ACCESS"optional

Options: EFFECTIVE_ACCESS, CONFIGURED

relates_to_expobjectoptional

A boolean expression describing the "relates to" types.

path_summary_node_typesobjectoptional

all_entity_conditionobjectoptional

path_summary_count_conditionsobjectoptional

result_value_typestring · enum · default: "UNDEFINED"optional

AssessmentQueryResultValueType determines which of the fields (values or path_values) will be populated in the resulting AssessmentQueryNodesResponse message. UNDEFINED is a valid selection and is intended for backward compatibility. When UNDEFINED is selected, the actual result value type will be determined by the backend (BE).

• UNDEFINED: Valid selection and intended for backward compatibility, result type determined by BE
• SOURCE_NODES_WITH_COUNTS: Returns populated values field containing source nodes and their destination counts
• SOURCE_AND_DESTINATION_NODES: Returns path_values with source and destination nodes, excluding path summary.
• PATHS: Returns path_values along with path summary.

Options: UNDEFINED, SOURCE_NODES_WITH_COUNTS, SOURCE_AND_DESTINATION_NODES, PATHS

page_sizestring · int64optional

The maximum number of results to be returned. Fewer results may be returned even when more pages exist.

page_tokenstringoptional

The token specifying the specific page of results to retrieve.

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/v1/assessments/query_spec:nodes' \
  --header 'Bearer: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "query_type": "SYSTEM_CREATED",
    "source_node_types": {
      "nodes": [
        "[Circular Reference]"
      ],
      "nodes_operator": "AND"
    },
    "destination_node_types": {
      "nodes": [
        "[Circular Reference]"
      ],
      "nodes_operator": "AND"
    },
    "required_intermediate_node_types": {
      "nodes": [
        "[Circular Reference]"
      ],
      "nodes_operator": "AND"
    },
    "avoided_intermediate_node_types": {
      "nodes": [
        "[Circular Reference]"
      ],
      "nodes_operator": "AND"
    },
    "raw_permissions": {
      "values": [
        "text"
      ],
      "operator": "AND"
    },
    "effective_permissions": {
      "values": [
        "METADATA_WRITE"
      ],
      "operator": "AND"
    },
    "customized_variables": [
      {
        "key": "text",
        "value": "text"
      }
    ],
    "no_relation": true,
    "snapshot_id": "text",
    "node_relationship_type": "EFFECTIVE_ACCESS",
    "relates_to_exp": {
      "specs": [
        "[Circular Reference]"
      ],
      "child_expressions": [
        "[Circular Reference]"
      ],
      "operator": "AND",
      "not": true,
      "and_op_type": "INFERRED"
    },
    "path_summary_node_types": {
      "nodes": [
        "[Circular Reference]"
      ],
      "nodes_operator": "AND"
    },
    "all_entity_condition": {
      "specs": [
        {
          "fn": "EQ",
          "property": "text",
          "value": null,
          "not": true,
          "value_property_name": "text",
          "value_property_from_other_node": true
        }
      ],
      "child_expressions": [
        "[Circular Reference]"
      ],
      "operator": "AND",
      "not": true
    },
    "path_summary_count_conditions": {
      "conditions": [
        {
          "fn": "EQ",
          "value": "text",
          "value_as": "COUNT"
        }
      ]
    },
    "result_value_type": "UNDEFINED",
    "page_size": "text",
    "page_token": "text"
  }'

200

401

403

404

500

502

503

200

{
  "values": [
    {
      "id": "text",
      "type": "text",
      "properties": {},
      "destination_node_count": 1,
      "permissions": "[Circular Reference]",
      "engagement_access_stats": {
        "engagement_score": 1,
        "over_provisioned_score": 1,
        "total_count": "text",
        "accessed_count": "text"
      },
      "access_stats": {
        "last_used": "2025-03-28T21:31:07.342Z",
        "count": 1,
        "concrete_permissions": [
          "text"
        ],
        "canonical_permissions": [
          "text"
        ]
      },
      "destination_node_ids": [
        "text"
      ],
      "risk_level": "NONE",
      "raw_permissions": [
        "text"
      ],
      "effective_permissions": [
        "text"
      ],
      "destination_node_percentage_of_total": 1
    }
  ],
  "path_values": [
    {
      "source": "[Circular Reference]",
      "abstract_permissions": [
        "text"
      ],
      "concrete_permissions": [
        "text"
      ],
      "destination": "[Circular Reference]",
      "path_summary_nodes": "[Circular Reference]",
      "results_truncated": true
    }
  ],
  "next_page_token": "text",
  "has_more": true
}

A successful response.

Sample request:

The following example searches for AWS IAM users with permissions to modify S3 bucket ACLs:

curl -X 'POST' \
"$BASE_URL/api/v1/assessments/query_spec:nodes?page_size=1&page_token=" \
-H "authorization: Bearer $VEZA_TOKEN" \
-d '{
  "query_type": "SOURCE_TO_DESTINATION",
  "include_nodes": true,
  "source_node_types": {
    "nodes": [
      {
        "node_type": "AwsIamUser"
      }
    ]
  },
  "destination_node_types": {
    "nodes": [
      {
        "node_type": "S3Bucket"
      }
    ]
  },
  "no_relation": false,
  "raw_permissions": {
    "operator": "OR",
    "values": [
      "s3:PutBucketAcl"
    ]
  }
}'

Sample response:

{
  "values": [
    {
      "id": "arn:aws:iam::877042069677:user/j.smith",
      "type": "AwsIamUser",
      "properties": {
        "aws_account_id": "877042069677",
        "created_at": "2021-11-15T15:14:47Z",
        "datasource_id": "877042069677:awsiam",
        "full_admin": true,
        "identity_unique_id": "j.smith",
        "last_used_at": "2023-05-25T00:00:00Z",
        "name": "j.smith",
        "password_last_used_at": "2023-05-25T00:00:00Z",
        "permission_boundary_controlled": false,
        "programmatic_access_count": 1,
        "programmatic_last_used_at": "2022-04-20T00:00:00Z",
        "provider_id": "877042069677",
        "root": false,
        "user_type": ""
      },
      "destination_node_count": 25,
      "permissions": [],
      "engagement_access_stats": null,
      "access_stats": null,
      "destination_node_ids": [],
      "risk_level": "CRITICAL",
      "raw_permissions": [],
      "effective_permissions": []
    }
  ],
  "path_values": [],
  "next_page_token": "eyJGaXJzdCI6eyJkdXBsaWNhdGlvbl9zY29wZV9pZCI6IjRmYWIxZDUyLWYzZjgtNGNkZS05MmVmLWVmZTc4OThlM2M2MCIsImlkIjoiYXJuOmF3czppYW06Ojg3NzA0MjA2OTY3Nzp1c2VyL2Fhcm9uLmJpbmZvcmQiLCJsb3dlcl9uYW1lIjoiYWFyb24uYmluZm9yZCJ9LCJMYXN0Ijp7ImR1cGxpY2F0aW9uX3Njb3BlX2lkIjoiNGZhYjFkNTItZjNmOC00Y2RlLTkyZWYtZWZlNzg5OGUzYzYwIiwiaWQiOiJhcm46YXdzOmlhbTo6ODc3MDQyMDY5Njc3OnVzZXIvYWFyb24uYmluZm9yZCIsImxvd2VyX25hbWUiOiJhYXJvbi5iaW5mb3JkIn19",
  "has_more": true
}

Here is a more complex example, which identifies Okta Users related to Snowflake Local Roles.

Using conditions, the query will only return users related to the BILLING group AND another group, either the AUDITOR role OR ROLE_A

Request:

curl -X 'POST' \
"$BASE_URL/api/v1/assessments/query_spec:nodes?page_size=1&page_token=" \
-H "authorization: Bearer $VEZA_TOKEN" \
-d '{"query_type":"SOURCE_TO_DESTINATION","source_node_types":{"nodes":[{"node_type":"OktaUser","tags":[],"conditions":[],"condition_expression":null,"node_id":"","excluded_tags":[],"count_conditions":[],"direct_relationship_only":false,"node_type_grouping_constraint":null}],"nodes_operator":"AND"},"destination_node_types":null,"required_intermediate_node_types":null,"avoided_intermediate_node_types":null,"raw_permissions":null,"effective_permissions":null,"customized_variables":[],"no_relation":false,"snapshot_id":"0","access_filter":null,"node_relationship_type":"EFFECTIVE_ACCESS","relates_to_exp":{"specs":[{"node_types":{"nodes":[{"node_type":"SnowflakeRole","tags":[],"conditions":[],"condition_expression":{"specs":[{"fn":"EQ","property":"id","value":"dn44266.us-east-2.aws.snowflakecomputing.com/role/BILLING","not":false,"value_property_name":"","value_property_from_other_node":false}],"child_expressions":[],"operator":"AND","not":false},"node_id":"","excluded_tags":[],"count_conditions":[],"direct_relationship_only":false,"node_type_grouping_constraint":null}],"nodes_operator":"AND"},"required_intermediate_node_types":null,"avoided_intermediate_node_types":null,"raw_permissions":null,"effective_permissions":{"values":[],"operator":"OR"},"no_relation":false,"direction":"ANY_DIRECTION"}],"child_expressions":[{"specs":[{"node_types":{"nodes":[{"node_type":"SnowflakeRole","tags":[],"conditions":[],"condition_expression":{"specs":[{"fn":"EQ","property":"id","value":"dn44266.us-east-2.aws.snowflakecomputing.com/role/AUDITOR","not":false,"value_property_name":"","value_property_from_other_node":false}],"child_expressions":[],"operator":"AND","not":false},"node_id":"","excluded_tags":[],"count_conditions":[],"direct_relationship_only":false,"node_type_grouping_constraint":null}],"nodes_operator":"AND"},"required_intermediate_node_types":null,"avoided_intermediate_node_types":null,"raw_permissions":null,"effective_permissions":{"values":[],"operator":"OR"},"no_relation":false,"direction":"ANY_DIRECTION"},{"node_types":{"nodes":[{"node_type":"SnowflakeRole","tags":[],"conditions":[],"condition_expression":{"specs":[{"fn":"EQ","property":"id","value":"dn44266.us-east-2.aws.snowflakecomputing.com/role/ROLE_A","not":false,"value_property_name":"","value_property_from_other_node":false}],"child_expressions":[],"operator":"AND","not":false},"node_id":"","excluded_tags":[],"count_conditions":[],"direct_relationship_only":false,"node_type_grouping_constraint":null}],"nodes_operator":"AND"},"required_intermediate_node_types":null,"avoided_intermediate_node_types":null,"raw_permissions":null,"effective_permissions":{"values":[],"operator":"OR"},"no_relation":false,"direction":"ANY_DIRECTION"}],"child_expressions":[],"operator":"OR","not":false,"and_op_type":"INFERRED"}],"operator":"AND","not":false,"and_op_type":"SOURCE_INTERSECT"},"path_summary_node_types":null,"all_entity_condition":null}'

Response:

{"values":[{"id":"00upfs3bV7G3ImWCL5d5","type":"OktaUser","properties":{"created_at":"2020-11-12T21:10:47Z","datasource_id":"dev-5150036.okta.com","email":"[e-mail]","first_name":"Simona","idp_unique_id":"[e-mail]","is_active":true,"last_name":"Morasca","login":"[e-mail]","mfa_active":false,"name":"[e-mail]","provider_id":"dev-5150036.okta.com","status":"STAGED","updated_at":"2020-11-12T21:10:47Z"},"destination_node_count":0,"permissions":[],"engagement_access_stats":null,"access_stats":null,"destination_node_ids":[],"risk_level":"CRITICAL","raw_permissions":[],"effective_permissions":[]}],"path_values":[],"next_page_token":"eyJGaXJzdCI6eyJkdXBsaWNhdGlvbl9zY29wZV9pZCI6IjQwZjFlZGZiLWQ1Y2UtNGU4ZC1hNWVmLWY2MzhmMDgxYzMzYiIsImlkIjoiMDB1Nmg4cnI2dkFzSUJqMW41ZDciLCJsb3dlcl9uYW1lIjoiYWFyb24uYmluZm9yZEB2ZXphdGVzdC5jb20ifSwiTGFzdCI6eyJkdXBsaWNhdGlvbl9zY29wZV9pZCI6IjQwZjFlZGZiLWQ1Y2UtNGU4ZC1hNWVmLWY2MzhmMDgxYzMzYiIsImlkIjoiMDB1NTJzc3FldkozQ1d3QlM1ZDciLCJsb3dlcl9uYW1lIjoieXV3dUB2ZXphLmNvbSJ9fQ==","has_more":false}