VQL API
API documentation for executing VQL queries through the Assessment Query API.
Overview
You can programmatically execute Veza Query Language (VQL) queries through Veza's Assessment Query API. This interface allows you to run VQL queries against Veza's Access Graph and retrieve results using standard REST API calls.
VQL vs. Traditional Approaches
VQL offers a simplified way to interact with Veza's Assessment Query APIs, enabling:
Automated compliance monitoring
Cross-platform integration
Custom investigation and reporting tools built on top of the Veza graph
While Veza's traditional JSON-based interfaces provide robust programmatic functionality, they are developer-focused and require detailed specification of all query components. VQL, with its SQL-like syntax, is more accessible to security practitioners who may already be familiar with similar query languages.
Example Comparison
Here's how the same query appears in both formats:
Traditional JSON Format:
{
"query_type": "SOURCE_TO_DESTINATION",
"source_node_types": {
"nodes": [
{
"node_type": "AwsIamUser",
"condition_expression": {
"specs": [
{
"fn": "EQ",
"property": "is_active",
"value": true
}
]
}
}
]
},
"destination_node_types": {
"nodes": [
{
"node_type": "S3Bucket"
}
]
}
}Equivalent VQL:
SHOW AwsIamUser WHERE is_active = true RELATED_TO S3BucketVQL's concise syntax makes queries easier to write, review, and troubleshoot while maintaining the power of Veza's assessment capabilities.
Requirements
To use the VQL API, you will need:
A valid API token. For details on obtaining and using API tokens, see Authentication.
Basic understanding of VQL syntax (see VQL Syntax)
VQL features enabled in your Veza instance
API Endpoints
The VQL API provides two primary endpoints for retrieving query results: Get Query Results (Count) and Get Query Results (Nodes).
Get Query Results (Count)
This endpoint retrieves result counts for a VQL query. These queries can execute faster and are optimal for metrics, reporting, and dashboard use cases where you need the total count rather than detailed node information.
The maximum number of results to be returned. Fewer results may be returned even when more pages exist.
The token specifying the specific page of results to retrieve.
POST /api/v1/assessments/vql:result HTTP/1.1
Host:
Authorization: Bearer Bearer <API key>
Content-Type: application/json
Accept: */*
Content-Length: 16
{
"query": "text"
}{
"result_type": "text",
"number_value": "text",
"timestamp_value": "text",
"nodes_value": {
"values": [
{
"id": "text",
"type": "text",
"properties": {},
"destination_node_count": 1,
"engagement_access_stats": {
"engagement_score": 1,
"over_provisioned_score": 1,
"total_count": "text",
"accessed_count": "text"
},
"access_stats": {
"last_used": "2025-07-03T03:01:38.098Z",
"count": 1,
"concrete_permissions": [
"text"
],
"canonical_permissions": [
"text"
]
},
"risk_level": 1,
"raw_permissions": [
"text"
],
"effective_permissions": [
"text"
],
"destination_node_percentage_of_total": 1,
"tags": [
{
"type": "text",
"key": "text",
"value": "text",
"properties": {
"ANY_ADDITIONAL_PROPERTY": null
}
}
],
"specified_tags": [
{
"type": "text",
"key": "text",
"value": "text",
"properties": {
"ANY_ADDITIONAL_PROPERTY": null
}
}
],
"filtered_raw_permissions": [
"text"
],
"corresponding_effective_permissions": [
"text"
],
"single_entity_access_stats": {
"last_used": "2025-07-03T03:01:38.098Z",
"last_used_with_events_for": [
{
"name": "text",
"last_used": "2025-07-03T03:01:38.098Z"
}
]
},
"additional_node_properties": {
"role_substitution_recommended_role": "text",
"role_substitution_reason_for_high_priv_role": "text",
"role_substitution_error": "text",
"default_cohort_role_users_in_cohort": [
"text"
],
"default_cohort_role": "text",
"default_cohort_role_all_common_roles": [
"text"
],
"default_cohort_role_error": "text",
"login_anomaly_detection_stats": [
{
"time": "2025-07-03T03:01:38.098Z",
"login_count": "text",
"median_login_count": 1,
"outlier_prediction": 1
}
],
"outlier_prediction": {
"prediction": 1,
"score": 1,
"contributing_features": [
{
"name": "text",
"value": 1,
"explanation": "text"
}
]
}
},
"integration_type": "text"
}
],
"next_page_token": "text",
"has_more": true
},
"result_statistics": {
"max_destination_node_count": "text",
"min_destination_node_count": "text",
"avg_destination_node_count": 1
},
"approx_total_source_nodes_count": "text"
}Get Query Results (Nodes)
The vql:nodes endpoint retrieves detailed results for VQL queries, showing source nodes, their properties, and access relationship information. This format is useful for security analysis, access reviews, and permission auditing.
Example Request
POST /api/v1/assessments/vql:nodes
{
"query": "SHOW OktaUser WHERE is_active = true RELATED TO S3Bucket RESULT INCLUDE DESTINATION NODES LIMIT 50;"
}This example asks: "Show me all active Okta users who have access to AWS S3 buckets, include details about those buckets, and limit results to 50 entries."
Understanding the API Response
When you send a VQL query, Veza returns a structured JSON response with results based on the latest graph data. The response contains:
Path Values: Each entry represents a connection between a source and destination node
Source: Details about the source node, including properties and risk level
Permissions: Both high-level ("abstract") permissions and specific ("concrete") permissions
Destination: Information about the destination node the source can access
Example Response
{
"path_values": [
{
"source": {
"id": "00u5pqrs7xyP9uvw30z9",
"type": "OktaUser",
"properties": {
"email": "[email protected]",
"name": "[email protected]",
"first_name": "John",
"last_name": "Smith",
"is_active": true,
"identity_type": "HUMAN"
},
"risk_level": "CRITICAL"
},
"abstract_permissions": [
"MetadataRead"
],
"concrete_permissions": [
"s3:ListBucket"
],
"destination": {
"id": "arn:aws:s3:::aws-cloudtrail-logs-123456789012-abcdef12",
"type": "S3Bucket",
"properties": {
"name": "aws-cloudtrail-logs-123456789012-abcdef12",
"region": "us-east-1",
"block_public_access_enabled": true
},
"risk_level": "LOW"
}
}
],
"cursor": "eyJsaW1pdCI6NTAsInN0YXJ0IjpbInNlcV9pZP...",
"has_more": true
}Pagination
For queries that return large result sets, use pagination to retrieve results in manageable chunks using the LIMIT and AFTER CURSOR keywords in your VQL query:
Make an initial request with a specified limit (e.g.,
LIMIT 50)Check if
has_moreistruein the responseIf more results exist, make subsequent requests using the cursor token from the previous response with
AFTER CURSOR 'token'
Example initial request:
{
"query": "SHOW SnowflakeUser RELATED TO SnowflakeTable WITH EFFECTIVE PERMISSIONS = ANY ('DATA_DELETE') LIMIT 50;"
}For subsequent requests, use the cursor token from the previous response:
{
"query": "SHOW SnowflakeUser RELATED TO SnowflakeTable WITH EFFECTIVE PERMISSIONS = ANY ('DATA_DELETE') AFTER CURSOR 'elcl9uYW1lIjoicjJkMiJ9fQ==' LIMIT 50;"
}Returns results as source nodes with optional destination entities and paths.
The maximum number of results to be returned. Fewer results may be returned even when more pages exist.
The token specifying the specific page of results to retrieve.
POST /api/v1/assessments/vql:nodes HTTP/1.1
Host:
Authorization: Bearer Bearer <API key>
Content-Type: application/json
Accept: */*
Content-Length: 16
{
"query": "text"
}{
"values": [
{
"id": "text",
"type": "text",
"properties": {},
"destination_node_count": 1,
"engagement_access_stats": {
"engagement_score": 1,
"over_provisioned_score": 1,
"total_count": "text",
"accessed_count": "text"
},
"access_stats": {
"last_used": "2025-07-03T03:01:38.098Z",
"count": 1,
"concrete_permissions": [
"text"
],
"canonical_permissions": [
"text"
]
},
"risk_level": 1,
"raw_permissions": [
"text"
],
"effective_permissions": [
"text"
],
"destination_node_percentage_of_total": 1,
"tags": [
{
"type": "text",
"key": "text",
"value": "text",
"properties": {
"ANY_ADDITIONAL_PROPERTY": null
}
}
],
"specified_tags": [
{
"type": "text",
"key": "text",
"value": "text",
"properties": {
"ANY_ADDITIONAL_PROPERTY": null
}
}
],
"filtered_raw_permissions": [
"text"
],
"corresponding_effective_permissions": [
"text"
],
"single_entity_access_stats": {
"last_used": "2025-07-03T03:01:38.098Z",
"last_used_with_events_for": [
{
"name": "text",
"last_used": "2025-07-03T03:01:38.098Z"
}
]
},
"additional_node_properties": {
"role_substitution_recommended_role": "text",
"role_substitution_reason_for_high_priv_role": "text",
"role_substitution_error": "text",
"default_cohort_role_users_in_cohort": [
"text"
],
"default_cohort_role": "text",
"default_cohort_role_all_common_roles": [
"text"
],
"default_cohort_role_error": "text",
"login_anomaly_detection_stats": [
{
"time": "2025-07-03T03:01:38.098Z",
"login_count": "text",
"median_login_count": 1,
"outlier_prediction": 1
}
],
"outlier_prediction": {
"prediction": 1,
"score": 1,
"contributing_features": [
{
"name": "text",
"value": 1,
"explanation": "text"
}
]
}
},
"integration_type": "text"
}
],
"path_values": [
{
"source": {
"id": "text",
"type": "text",
"properties": {},
"destination_node_count": 1,
"engagement_access_stats": {
"engagement_score": 1,
"over_provisioned_score": 1,
"total_count": "text",
"accessed_count": "text"
},
"access_stats": {
"last_used": "2025-07-03T03:01:38.098Z",
"count": 1,
"concrete_permissions": [
"text"
],
"canonical_permissions": [
"text"
]
},
"risk_level": 1,
"raw_permissions": [
"text"
],
"effective_permissions": [
"text"
],
"destination_node_percentage_of_total": 1,
"tags": [
{
"type": "text",
"key": "text",
"value": "text",
"properties": {
"ANY_ADDITIONAL_PROPERTY": null
}
}
],
"specified_tags": [
{
"type": "text",
"key": "text",
"value": "text",
"properties": {
"ANY_ADDITIONAL_PROPERTY": null
}
}
],
"filtered_raw_permissions": [
"text"
],
"corresponding_effective_permissions": [
"text"
],
"single_entity_access_stats": {
"last_used": "2025-07-03T03:01:38.098Z",
"last_used_with_events_for": [
{
"name": "text",
"last_used": "2025-07-03T03:01:38.098Z"
}
]
},
"additional_node_properties": {
"role_substitution_recommended_role": "text",
"role_substitution_reason_for_high_priv_role": "text",
"role_substitution_error": "text",
"default_cohort_role_users_in_cohort": [
"text"
],
"default_cohort_role": "text",
"default_cohort_role_all_common_roles": [
"text"
],
"default_cohort_role_error": "text",
"login_anomaly_detection_stats": [
{
"time": "2025-07-03T03:01:38.098Z",
"login_count": "text",
"median_login_count": 1,
"outlier_prediction": 1
}
],
"outlier_prediction": {
"prediction": 1,
"score": 1,
"contributing_features": [
{
"name": "text",
"value": 1,
"explanation": "text"
}
]
}
},
"integration_type": "text"
},
"abstract_permissions": [
"text"
],
"concrete_permissions": [
"text"
],
"destination": {
"id": "text",
"type": "text",
"properties": {},
"destination_node_count": 1,
"engagement_access_stats": {
"engagement_score": 1,
"over_provisioned_score": 1,
"total_count": "text",
"accessed_count": "text"
},
"access_stats": {
"last_used": "2025-07-03T03:01:38.098Z",
"count": 1,
"concrete_permissions": [
"text"
],
"canonical_permissions": [
"text"
]
},
"risk_level": 1,
"raw_permissions": [
"text"
],
"effective_permissions": [
"text"
],
"destination_node_percentage_of_total": 1,
"tags": [
{
"type": "text",
"key": "text",
"value": "text",
"properties": {
"ANY_ADDITIONAL_PROPERTY": null
}
}
],
"specified_tags": [
{
"type": "text",
"key": "text",
"value": "text",
"properties": {
"ANY_ADDITIONAL_PROPERTY": null
}
}
],
"filtered_raw_permissions": [
"text"
],
"corresponding_effective_permissions": [
"text"
],
"single_entity_access_stats": {
"last_used": "2025-07-03T03:01:38.098Z",
"last_used_with_events_for": [
{
"name": "text",
"last_used": "2025-07-03T03:01:38.098Z"
}
]
},
"additional_node_properties": {
"role_substitution_recommended_role": "text",
"role_substitution_reason_for_high_priv_role": "text",
"role_substitution_error": "text",
"default_cohort_role_users_in_cohort": [
"text"
],
"default_cohort_role": "text",
"default_cohort_role_all_common_roles": [
"text"
],
"default_cohort_role_error": "text",
"login_anomaly_detection_stats": [
{
"time": "2025-07-03T03:01:38.098Z",
"login_count": "text",
"median_login_count": 1,
"outlier_prediction": 1
}
],
"outlier_prediction": {
"prediction": 1,
"score": 1,
"contributing_features": [
{
"name": "text",
"value": 1,
"explanation": "text"
}
]
}
},
"integration_type": "text"
},
"path_summary_nodes": [
{
"id": "text",
"type": "text",
"properties": {},
"destination_node_count": 1,
"engagement_access_stats": {
"engagement_score": 1,
"over_provisioned_score": 1,
"total_count": "text",
"accessed_count": "text"
},
"access_stats": {
"last_used": "2025-07-03T03:01:38.098Z",
"count": 1,
"concrete_permissions": [
"text"
],
"canonical_permissions": [
"text"
]
},
"risk_level": 1,
"raw_permissions": [
"text"
],
"effective_permissions": [
"text"
],
"destination_node_percentage_of_total": 1,
"tags": [
{
"type": "text",
"key": "text",
"value": "text",
"properties": {
"ANY_ADDITIONAL_PROPERTY": null
}
}
],
"specified_tags": [
{
"type": "text",
"key": "text",
"value": "text",
"properties": {
"ANY_ADDITIONAL_PROPERTY": null
}
}
],
"filtered_raw_permissions": [
"text"
],
"corresponding_effective_permissions": [
"text"
],
"single_entity_access_stats": {
"last_used": "2025-07-03T03:01:38.098Z",
"last_used_with_events_for": [
{
"name": "text",
"last_used": "2025-07-03T03:01:38.098Z"
}
]
},
"additional_node_properties": {
"role_substitution_recommended_role": "text",
"role_substitution_reason_for_high_priv_role": "text",
"role_substitution_error": "text",
"default_cohort_role_users_in_cohort": [
"text"
],
"default_cohort_role": "text",
"default_cohort_role_all_common_roles": [
"text"
],
"default_cohort_role_error": "text",
"login_anomaly_detection_stats": [
{
"time": "2025-07-03T03:01:38.098Z",
"login_count": "text",
"median_login_count": 1,
"outlier_prediction": 1
}
],
"outlier_prediction": {
"prediction": 1,
"score": 1,
"contributing_features": [
{
"name": "text",
"value": 1,
"explanation": "text"
}
]
}
},
"integration_type": "text"
}
],
"results_truncated": true,
"filtered_concrete_permissions": [
"text"
],
"corresponding_abstract_permissions": [
"text"
],
"filtered_concrete_permission_groups": [
{
"permissions": [
"text"
]
}
],
"joined_nodes": {
"ANY_ADDITIONAL_PROPERTY": {
"id": "text",
"type": "text",
"properties": {},
"destination_node_count": 1,
"engagement_access_stats": {
"engagement_score": 1,
"over_provisioned_score": 1,
"total_count": "text",
"accessed_count": "text"
},
"access_stats": {
"last_used": "2025-07-03T03:01:38.098Z",
"count": 1,
"concrete_permissions": [
"text"
],
"canonical_permissions": [
"text"
]
},
"risk_level": 1,
"raw_permissions": [
"text"
],
"effective_permissions": [
"text"
],
"destination_node_percentage_of_total": 1,
"tags": [
{
"type": "text",
"key": "text",
"value": "text",
"properties": {
"ANY_ADDITIONAL_PROPERTY": null
}
}
],
"specified_tags": [
{
"type": "text",
"key": "text",
"value": "text",
"properties": {
"ANY_ADDITIONAL_PROPERTY": null
}
}
],
"filtered_raw_permissions": [
"text"
],
"corresponding_effective_permissions": [
"text"
],
"single_entity_access_stats": {
"last_used": "2025-07-03T03:01:38.098Z",
"last_used_with_events_for": [
{
"name": "text",
"last_used": "2025-07-03T03:01:38.098Z"
}
]
},
"additional_node_properties": {
"role_substitution_recommended_role": "text",
"role_substitution_reason_for_high_priv_role": "text",
"role_substitution_error": "text",
"default_cohort_role_users_in_cohort": [
"text"
],
"default_cohort_role": "text",
"default_cohort_role_all_common_roles": [
"text"
],
"default_cohort_role_error": "text",
"login_anomaly_detection_stats": [
{
"time": "2025-07-03T03:01:38.098Z",
"login_count": "text",
"median_login_count": 1,
"outlier_prediction": 1
}
],
"outlier_prediction": {
"prediction": 1,
"score": 1,
"contributing_features": [
{
"name": "text",
"value": 1,
"explanation": "text"
}
]
}
},
"integration_type": "text"
}
},
"additional_path_properties": {
"outlier_prediction": {
"prediction": 1,
"score": 1,
"contributing_features": [
{
"name": "text",
"value": 1,
"explanation": "text"
}
]
}
}
}
],
"approx_total_source_nodes_count": "text",
"next_page_token": "text",
"has_more": true
}Related Documentation
VQL Syntax Reference - Complete documentation of VQL query syntax
VQL Quick Start Guide - Examples and usage patterns
Assessment Query API Overview - General information about the Assessment Query API
Last updated
Was this helpful?