---
title: "Generate Query Plan"
method: POST
path: "/planner/plan"
tags: ["HelixQL Planner"]
---

# Generate Query Plan

`POST /planner/plan`

## 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/planner/plan`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/metacognition/apis/tex-api/docs/planner/plan/post.ts> (a function with typed inputs; its response is checked against the schema)

## Request body

- QueryPlanRequest: Query plan generation request.
  - `query` string, required: Natural language query
  - `schema` PlannerSchema, required: Database schema for query planner.
    - `nodes` object, required: Node types
    - `edges` object, required: Edge types
  - `enable_pruning` boolean: Enable schema pruning
  - `use_local_intelligence` boolean: Use local intelligent planner

## Response `200`

Successful Response

- QueryPlanResponse: Query plan generation response.
  - `query_plan` object, required: Generated QueryPlan JSON
  - `query_type` string, required: Query type
  - `constraint_embeddings` object, nullable: Optional map of variable name -> 1024-d embedding for that variable's constraint string (BAAI/bge-large-en-v1.5 via emprocesser). If present, IntegrationBackend will forward this to HelixDB /intent/matches to enable vector-first constraint resolution.
  - `complexity_hints` object, nullable: Optional complexity hints from the planner (pass-through)
  - `latency_ms` number, required: Processing latency
  - `helix_ql` string, nullable: Generated HelixQL code
  - `entity` object, nullable: Detected entity info
  - `planner_version` string, nullable: Planner version used

## 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)