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
AuthorizationstringRequired

Veza API key for authentication. Generate keys in Administration > API Keys.

Query parameters
page_sizestringOptional

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.

order_bystringOptional

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

apply_risk_suppressed_constraintbooleanOptional

If it should apply the risk suppressed constraint

add_access_statsbooleanOptional

If it should get access stats for those available

skip_single_entity_access_statsbooleanOptional

If true, skips fetching single entity access stats (last used time, etc.) This is useful for performance optimization when access stats are not needed

Body

Assessment query specification defining access relationships to analyze. Specifies source entities, relationship expressions, and permission/access filters for querying the Veza Authorization Graph. Migration note: Several fields are deprecated in favor of relates_to_exp, which provides a more flexible boolean expression syntax for defining access relationships. Deprecated fields: destination_node_types, required_intermediate_node_types, avoided_intermediate_node_types, raw_permissions, effective_permissions, and no_relation.

query_typeinteger · enumOptional

The type of assessment query to execute (enum). Values: 0 = SYSTEM_CREATED, 1 = SOURCE_TO_DESTINATION, 2 = DESTINATION_NODES.

no_relationbooleanOptionalDeprecated

Deprecated. Use relates_to_exp instead. When true, queries for entities with no access relationship.

snapshot_idstringOptional

Optional snapshot ID to query against a specific point-in-time data snapshot.

node_relationship_typeinteger · enumOptional
result_value_typeinteger · enumOptional

Controls the shape of query results. Determines whether results contain source nodes with counts, source-and-destination node pairs, or other result formats.

include_all_source_tags_in_resultsbooleanOptional

These fields control whether or not tags will be included in source and/or destination results

include_all_destination_tags_in_resultsbooleanOptional
additional_columns_to_getinteger · enum[]Optional

Allows FE to Alert BE if permissions are being displayed to the user

include_sub_permissionsbooleanOptional

Include node with sub permissions which is a permission showing for a resource when in reality the permission applies to a subresource.

include_permissions_summarybooleanOptional

This field should be used with AssessmentQueryResultValueType SOURCE_NODES_WITH_COUNTS to include permissions summarized (aggregated) by source node, meaning it contains all permissions used by each source node

unpivot_propertiesstring[]Optional

The properties that should be unpivoted in the results producing multiple rows per node/path To be able to unpivot a property, it must be a list/array type property. If multiple properties are used result will be Cartesian product(all unpivot combinations for node). If property does not exist on a node, and it is a valid property, we will just add that node as is. Syntax to specify properties is the full path to the property using dot notation and using properties json names. Both values and pathValues can be unpivoted:

  1. Valid values for unpivoting: properties.<property_name>, unsupported_conditions.<condition_name>.conditions, joined_nodes..<valid_value_for_unpivoting>, raw_permissions, effective_permissions, access_stats.concrete_permissions, access_stats.canonical_permissions, filtered_raw_permissions, corresponding_effective_permissions, additional_node_properties.default_cohort_role_users_in_cohort, additional_node_properties.default_cohort_role_all_common_roles

  2. Valid pathValues for unpivoting: unsupported_conditions.<condition_name>.conditions, joined_nodes..<valid_value_for_unpivoting>, source.<valid_value_for_unpivoting>, destination.<valid_value_for_unpivoting>, waypoint.<valid_value_for_unpivoting>, abstract_permissions,concrete_permissions, filtered_concrete_permissions, corresponding_abstract_permissions Examples for Unpivoting values:

  3. Single field: unpivot_properties: ["properties.email_addresses"] result_values: {Values: [ {id:"1","properties"{"email_addresses":["[email protected]","[email protected]"]}} ]} After unpivot -> Multiple nodes with id 1: result_values: {Values: [ {id:"1","properties"{"email_addresses":"[email protected]"}}, {id:"1","properties"{"email_addresses":"[email protected]"}} ]}

  4. Single field with missing unpivot property: unpivot_properties: ["properties.email_addresses"] result_values: {Values: [ {id:"1","properties"{"permissions": "abc"]}} ]} After unpivot -> Single node with id 1 (no email_addresses property to unpivot): result_values: {Values: [ {id:"1","properties"{"permissions":"abc"}}, ]}

  5. Multiple fields - Cartesian Product: unpivot_properties: ["properties.email_addresses", "raw_permissions"] result_values: {Values: [ {id:"1","properties"{"email_addresses":["[email protected]","[email protected]"]}, "raw_permissions":["perm1","perm2"]} ]} After unpivot -> Multiple nodes with id 1: result_values: {Values: [ {id:"1","properties"{"email_addresses":"[email protected]"}, "raw_permissions":"perm1"}, {id:"1","properties"{"email_addresses":"[email protected]"}, "raw_permissions":"perm2"}, {id:"1","properties"{"email_addresses":"[email protected]"}, "raw_permissions":"perm1"}, {id:"1","properties"{"email_addresses":"[email protected]"}, "raw_permissions":"perm2"}, ]}

page_sizestringOptional

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
chevron-right
200

OK

application/json
approx_total_source_nodes_countstringOptional
next_page_tokenstringOptional

The token to retrieve the next page of results.

has_morebooleanOptional

If true, more results are available.

post
/api/v1/assessments/query_spec:nodes

Sample request:

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

Sample response:

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:

Response:

Last updated

Was this helpful?