**Source URL:** https://limited.veevavault.dev/clinical/vql/guides/query-profiler.md # Tracking Query Performance with Query Profiler Query Profiler provides a centralized log for all VQL queries run using both Vault API and Vault Java SDK QueryService. During a session, the profiler records query data in a single log. You can use this record to analyze, troubleshoot, and optimize the performance of all your queries. For example, Query Profiler can reveal whether any of your Vault’s queries are running slowly or are consistently reporting no data. You can also identify gaps between the data the query returns and the data the SDK code can access. Only one profiler session can be active at a time. The max query length is 50,000 characters. ## Prerequisites {#prerequisites} You must have the *Admin: Logs*: *Developer* permission to start, end, or download profiler sessions. ## Creating a Session with Filters {#creating-a-session-with-filters} You can create a new profiler session using Vault API v26.2+ and the Create New Session endpoint. When starting a profiler session, add filters to capture results for specific aspects such as user, query target, or result count. Add each filter as a body parameter in the Vault API request. You cannot change filters for an active session. ### User & Origin {#user--origin} By default, Query Profiler looks at queries initiated by all users in the Vault. You can identify a specific user to profile by providing the `user_id` as a filter. This allows you to isolate and analyze only those queries generated by a specific user. The `query_origin` filter determines whether a query originated from the Vault API or Vault Java SDK (or both). Select `api` to capture queries from Vault API calls, or `sdk` for queries executed with Vault Java SDK `QueryService`. For a comprehensive view of how different interfaces interact, use `all` to capture both sources. ### Query Target {#query-target} The `query_targets` filter allows you to profile specific Vault query targets. To isolate query target traffic, provide a comma-separated list of up to 20 target names. This is useful for troubleshooting an integration that targets specific data such as `documents` and `product__v`. If this parameter is omitted or set to `all`, the session monitors all available VQL targets in the Vault. You can use this when auditing the performance of all targets. ### Performance Thresholds {#performance-thresholds} The `result_count` and `query_time` filters allow you to isolate queries based on specific performance criteria instead of reviewing every query executed during a session. To identify discrepancies between data retrieval and data processing, set the `result_count_min` and `result_count_max` filters. Use this to verify why a query is returning a high volume of records while the associated SDK code only accesses some of them. To find performance bottlenecks, use the `query_time_min` and `query_time_max` filters to capture queries within a specific range of execution times. Setting only a minimum duration allows you to filter out fast, performant queries and focus on those that exceed the specified execution time. For example, set a minimum duration of 5 seconds to isolate queries that are running very slowly. If the initial query execution time is not captured (such as when a session is already active), the profiler still includes the record in the resulting log to ensure visibility. ### Response Status {#response-status} The `response_status` filter allows you to isolate queries based on the outcome of their execution. To identify syntax errors or permission issues, set the filter to `error`. This captures queries that failed to execute and provides the corresponding error message (truncated to 1,500 characters) and `error_type`. To investigate areas of improvement, use the `warn` status. This captures queries that have completed but triggered system warnings. The `success` status captures queries that were executed as intended. A `success` status may still be returned even if `num_records_returned` is `0`. When the `response_status` parameter is omitted or set to `all`, the profiler captures every query regardless of the result. ## Viewing & Interpreting Results {#viewing--interpreting-results} Use the List All Sessions endpoint to retrieve a list of all profiler sessions in your Vault, including their current status and metadata. To view a specific session, use the List Single Session endpoint and specify the `{session_name}` in the path. Use these calls to track the `status` of a session and identify the specific `expiration_date`, which is 30 days after session creation. To download session results, use the Download Session Results endpoint. This returns a `.zip` file containing a single CSV log file. Results are available around 15 minutes after a session ends. When interpreting the CSV log, look for the following performance indicators: * A higher `num_records_returned` than `num_records_accessed` indicates queries may be inefficiently retrieving more data than the Vault Java SDK logic requires. * The `query_execution_time_subsequent_pages` and the initial `query_execution_time` values may reveal bottlenecks during page offset and page retrieval. * The `error` and `error_type` columns indicate why specific queries failed. * If a page of results is requested multiple times, the log aggregates the execution time and accessed records into a single row for that query. This allows you to see the total resource impact of a single VQL execution across its entire lifecycle. ## Ending a Session {#ending-a-session} To manually terminate an active session before it completes, use the End Active Session endpoint. A session also terminates automatically when it reaches the defined limits, either 20 minutes of data or 10,000 queries. To delete a session record and its associated log file from the Vault, use the Delete Session endpoint. Deleting logs helps manage the storage limit of captured sessions (default 10). --- **Previous:** [Guides](/clinical/vql/guides) **Next:** [Clauses](/clinical/vql/clauses)