Create async query nodes

Asynchronously execute a saved assessment query by ID and return node-level results.

This is the async equivalent of Get query nodes, for saved queries that may return large result sets or take longer than the synchronous request timeout allows.

post

Authorizations

bearerAuth

AuthorizationstringRequired

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

Path parameters

idstringRequired

Body

application/json

idstringOptional

snapshot_idstringOptional

apply_risk_suppressed_constraintbooleanOptional

properties_to_getstring[]Optional

The properties that are returned on node, this allows the ability to limit the amount of properties retrieved through the graph This currently is only available on the source_node_types collection If used during an export, it is supported for source_node_types, relates_to_expression.node_types and path summary node types. In this case, the field is used to filter which properties will be exported, in the order in which they are specified.

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

fetch_cached_resultsbooleanOptional

include_approx_total_source_nodes_countbooleanOptional

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

destination_node_count ASC and destination_node_count DESC are valid values

cache_strategyinteger · enumOptional

Cache strategy to use. Defaults to CACHE_STRATEGY_LEGACY for backward compatibility.

result_order_bystringOptional

Field sorting to apply to the query results, using SQL ORDER BY syntax. Multiple sort fields can be specified, separated by commas. Each field can optionally specify ASC (ascending, default) or DESC (descending).

Field naming follows the same rules as the filters field:

• PATH queries: use "source.", "destination.", or no prefix for path-level fields
• NODE queries: use fields directly without prefix

All filterable fields (see filters field documentation) are also sortable. Some string fields (properties.name and properties.email) are sorted case-insensitively.

Examples:

• destination_node_count DESC
• destination.properties.risk_score DESC, source.id ASC
• engagement_access_stats.engagement_score DESC
• source.integration_type ASC, destination.type ASC
• properties.email DESC
• access_stats.last_used DESC

When aggregation/group_by is enabled, order_by is restricted to:

• The group_by field itself (e.g., "type")
• Aggregation result fields (e.g., "count" for OP_COUNT) Examples with aggregation:
• count DESC (sort by aggregation result)
• type ASC (sort by group_by field)
• integration_type DESC (if grouping by integration_type)

Responses

200

OK

application/json

Response containing identifiers for polling async query results and reusing cached executions.

query_result_idstringOptional

Unique task identifier for this query execution. Use with GetQuerySpecNodesAsync to poll for status and retrieve results when complete.

last_completed_cache_idstringOptional

The most recent completed cache identifier for the same query specification. Use this with cached_result_context to immediately retrieve cached results without waiting for a new execution. Empty if no cached execution exists or this is a cached_result_context request.

cache_idstringOptional

The cache identifier that this query task is using for its execution. Can be used in future cached_result_context requests.

default

Default error response

application/json

post

/api/v1/assessments/queries/{id}:nodes_async_create

HTTPcURLJavaScriptPython

POST /api/v1/assessments/queries/{id}:nodes_async_create HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 368

{
  "id": "text",
  "snapshot_id": "text",
  "apply_risk_suppressed_constraint": true,
  "properties_to_get": [
    "text"
  ],
  "include_all_source_tags_in_results": true,
  "include_all_destination_tags_in_results": true,
  "fetch_cached_results": true,
  "include_approx_total_source_nodes_count": true,
  "page_size": "text",
  "page_token": "text",
  "order_by": "text",
  "cache_strategy": 1,
  "result_order_by": "text"
}

{
  "query_result_id": "text",
  "last_completed_cache_id": "text",
  "cache_id": "text"
}

Path parameter

Parameter	Description
id	The ID of a saved assessment query to execute.

Request options

Field	Description
snapshot_id	Query against a specific point-in-time data snapshot.
properties_to_get	Limit which properties are returned on source nodes.
include_all_source_tags_in_results	Include tags in source node results.
include_all_destination_tags_in_results	Include tags in destination node results.
fetch_cached_results	Return cached results if available.
include_approx_total_source_nodes_count	Include approximate total source node count.
page_size / page_token	Control pagination of results.
order_by	Sort results (e.g., destination_node_count DESC).
cache_strategy	Cache strategy to use. Defaults to CACHE_STRATEGY_LEGACY.

Workflow

1. Submit a saved query for async execution using this endpoint with the query id.

2. The response includes query_result_id, last_completed_cache_id, and cache_id.

3. If last_completed_cache_id is present, cached results are available immediately.

4. Poll results using the query_result_id until the query completes.

5. Retrieve paginated results from the response when status = DONE.