---
title: "Execute an ad-hoc query (simple)"
method: GET
path: "/v1/query"
tags: ["Query API"]
---

# Execute an ad-hoc query (simple)

`GET /v1/query`

This API endpoint returns bindings for the variables in the query.

For more complex JSON queries, use `POST /v1/query` instead.

## Query parameters

- `q` string, required
- `pretty` boolean
- `explain` string
- `metrics` boolean

## Response `200`

Success

- object
  - `result` object[]
    - `id` string — The name of a policy module
    - `raw` string — A string representation of the full Rego policy
    - `ast` object — The types for declarations and runtime objects passed to your implementation. This consists of an abstract syntax tree (AST) of policy modules, package and import declarations, rules, expressions, and terms.
      - `package` object
        - `path` object[] — The path to the package
          - `type` 'import' | 'package' — The type of the path operation
          - `value` string — The path variable
      - `rules` object[] — When OPA evaluates a rule, it generates the content of a [virtual documents](https://www.openpolicyagent.org/docs/latest/philosophy/#the-opa-document-model)
        - `head` object
          - `name` string — The head of the rule
          - `key` object — The type/value pairing for this rule's head
            - `type` string — The type of the head
            - `value` string — The value of the head
        - `body` object[] — A list of the terms in this rule
          - `index` number — The location of this term in the list (starts at 0)
          - `terms` object[] — The type/value pairing for this term
            - `type` string — The type of the term variable
            - `value` object[] — The list of types and values for the term variable
              - …
  - `metrics` object
    - `timer_rego_input_parse_ns` number — Time taken (in nanonseconds) to parse the input
    - `timer_rego_query_parse_ns` number — Time taken (in nanoseconds) to parse the query
    - `timer_rego_query_compile_ns` number — Time taken (in nanoseconds) to compile the query
    - `timer_rego_query_eval_ns` number — Time taken (in nanonseconds) to evaluate the query
    - `timer_rego_module_parse_ns` number — Time taken (in nanoseconds) to parse the input policy module
    - `timer_rego_module_compile_ns` number — Time taken (in nanonseconds) to compile the loaded policy modules
    - `timer_server_handler_ns` number — Time taken (in nanoseconds) to handle the API request
    - `timer_server_read_bytes_ns` number — *Description is forthcoming*
    - `counter_server_query_cache_hit` number — *Description is forthcoming*
    - `timer_query_compile_stage_build_comprehension_index_ns` number — (Only returned if `instrument` is true.) *Description is forthcoming*
    - `timer_query_compile_stage_check_safety_ns` number — (Only returned if `instrument` is true.) *Description is forthcoming*
    - `timer_query_compile_stage_check_types_ns` number — (Only returned if `instrument` is true.) *Description is forthcoming*
    - `timer_query_compile_stage_check_undefined_funcs_ns` number — (Only returned if `instrument` is true.) *Description is forthcoming*
    - `timer_query_compile_stage_check_unsafe_builtins_ns` number — (Only returned if `instrument` is true.) *Description is forthcoming*
    - `timer_query_compile_stage_resolve_refs_ns` number — (Only returned if `instrument` is true.) *Description is forthcoming*
    - `timer_query_compile_stage_rewrite_comprehension_terms_ns` number — (Only returned if `instrument` is true.) *Description is forthcoming*
    - `timer_query_compile_stage_rewrite_dynamic_terms_ns` number — (Only returned if `instrument` is true.) *Description is forthcoming*
    - `timer_query_compile_stage_rewrite_expr_terms_ns` number — (Only returned if `instrument` is true.) *Description is forthcoming*
    - `timer_query_compile_stage_rewrite_local_vars_ns` number — (Only returned if `instrument` is true.) *Description is forthcoming*
    - `timer_query_compile_stage_rewrite_to_capture_value_ns` number — (Only returned if `instrument` is true.) *Description is forthcoming*
    - `timer_query_compile_stage_rewrite_with_values_ns` number — (Only returned if `instrument` is true.) *Description is forthcoming*
  - `explanation` object[]
    - `op` 'enter' | 'exit' | 'eval' | 'fail' | 'redo' — The kind of *trace event* Each trace event represents a step in the query evaluation process. Trace events are emitted at the following points: - enter - before a body or rule is evaluated - exit - after a body or rule has evaluated successfully - eval - before an expression is evaluated - fail - after an expression has evaluated to false. - redo - before evaluation restarts from a body, rule, or expression. By default, OPA searches for all sets of term bindings that make all expressions in the query evaluate to true. Because there may be multiple answers, the search can restart when OPA determines the query is true or false. When the search restarts, a *redo trace event* is emitted.
    - `query_id` number — The query that the trace event was emitted for. Use this field to distinguish trace events emitted by from different queries.
    - `parent_id` number — The parent query. Use this field to identify trace events from related queries. For example, if query A references rule R, trace events emitted when evaluating rule R will have the *parent_id* field set to query A’s *query_id*.
    - `type` 'expr' | 'rule' | 'body' — The type of the **node** field
    - `node` object — The AST element associated with the evaluation step.
      - `index` number — Node number
      - `terms` object[]
        - `type` string
        - `value` string
    - `locals` object[] — The query's term bindings at the point when the trace event was emitted.
      - `key` object
        - `type` string
        - `value` string
      - `value` object
        - `type` string
        - `value` string

## Other responses

- `400` — Bad request
- `500` — Server error

---

[API](https://skmtc.net/open-policy-agent/apis/open-policy-agent-opa-rest-api.md) · [All operations](https://skmtc.net/open-policy-agent/apis/open-policy-agent-opa-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/open-policy-agent/open-policy-agent-opa-rest-api/revisions/47f6f2062932/schema)