---
title: "Execute Query"
method: POST
path: "/helixdb/query"
tags: ["HelixDB"]
---

# Execute Query

`POST /helixdb/query`

## Request

- Base URL: `https://api.getmetacognition.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.getmetacognition.com/helixdb/query`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/metacognition/apis/tex-api/docs/helixdb/query/post.ts> (a function with typed inputs; its response is checked against the schema)

Execute dynamic HelixQL.

Optional `scope` ("<kind>:<value>") stamps any writes the query performs
(X-Scope-Id); mutating queries can't be distinguished here, so it is a
pass-through — the engine's own write gate (D-2) is authoritative. Must be
within the caller's visible scopes (403 otherwise).

## Request body

- QueryRequest: Execute dynamic HelixQL query.
  - `query` string, required: HelixQL query string
  - `params` object: Query parameters
  - `scope` string, nullable: Optional explicit write scope "<kind>:<value>" (kinds: user/team/org/project). Must be within the caller's visible scopes; defaults to user:<user_id>.

## Response `200`

Successful Response

- QueryResponse: Query execution response.
  - `success` boolean, required: Whether query succeeded
  - `data` unknown
  - `error` string, nullable: Error message if failed

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/metacognition/apis/tex-api.md) - [All operations](https://skmtc.dev/metacognition/apis/tex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/metacognition/apis/tex-api/revisions/3bef47e50f2e?raw)