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.

Example use:

POST /api/v1/assessments/vql:nodes

{
  "query": "SHOW OktaUser WHERE is_active = false AND last_login_at < CURRENT_DATE - 90 RELATED TO S3Bucket WITH PATH AwsIamRole RESULT INCLUDE DESTINATION NODES LIMIT 50;"
}

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.

Retrieves the result count for the given VQL query.

post

Authorizations

Body

querystringoptional

page_sizestringoptionalDeprecated

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

page_tokenstringoptionalDeprecated

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/vql:result' \
  --header 'Authorization: Bearer Bearer <API key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "text",
    "page_size": "text",
    "page_token": "text"
  }'

200

default

200

{
  "result_type": "text",
  "number_value": "text",
  "timestamp_value": "text",
  "nodes_value": {
    "values": [
      "[Circular Reference]"
    ],
    "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"
}

OK

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.

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:

1. Make an initial request with a specified limit (e.g., LIMIT 50)

2. Check if has_more is true in the response

3. If 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;"
}

Retrieves the result nodes for the given VQL query.

post

Returns results as source nodes with optional destination entities and paths.

Authorizations

Body

querystringoptional

page_sizestringoptionalDeprecated

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

page_tokenstringoptionalDeprecated

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/vql:nodes' \
  --header 'Authorization: Bearer Bearer <API key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "text",
    "page_size": "text",
    "page_token": "text"
  }'

200

default

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-31T13:00:32.123Z",
        "count": 1,
        "concrete_permissions": [
          "text"
        ],
        "canonical_permissions": [
          "text"
        ]
      },
      "destination_node_ids": [
        "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-03-31T13:00:32.123Z",
        "last_used_with_events_for": [
          {
            "name": "text",
            "last_used": "2025-03-31T13:00:32.123Z"
          }
        ]
      },
      "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-03-31T13:00:32.123Z",
            "login_count": "text",
            "median_login_count": 1,
            "outlier_prediction": 1
          }
        ]
      }
    }
  ],
  "path_values": [
    {
      "source": "[Circular Reference]",
      "abstract_permissions": [
        "text"
      ],
      "concrete_permissions": [
        "text"
      ],
      "destination": "[Circular Reference]",
      "path_summary_nodes": "[Circular Reference]",
      "results_truncated": true,
      "filtered_concrete_permissions": [
        "text"
      ],
      "corresponding_abstract_permissions": [
        "text"
      ],
      "filtered_concrete_permission_groups": [
        {
          "permissions": [
            "text"
          ]
        }
      ],
      "joined_nodes": "[Circular Reference]"
    }
  ],
  "approx_total_source_nodes_count": "text",
  "next_page_token": "text",
  "has_more": true
}

OK

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