---
title: "Nlq Execute"
method: POST
path: "/nlq/execute"
tags: ["NLQ"]
---

# Nlq Execute

`POST /nlq/execute`

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

## Request body

- NLQExecuteRequest: Natural language query -> plan -> execute request.
  - `query` string, required: Natural language query to execute
  - `enable_pruning` boolean: Enable schema pruning (planner)
  - `use_local_intelligence` boolean: Use local intelligent planner (planner)
  - `execute` boolean: If true, execute IntentGraph via intent matching
  - `enrich` boolean: If true, enrich results with neighboring nodes/edges for agent context (DEPRECATED - use intent matching)
  - `enrich_limit` integer: Max neighbors per edge type during enrichment (DEPRECATED)
  - `compact` boolean: If true, return agent-friendly output (redact internal fields, keep only relevant context)
  - `require_helix_ql` boolean: DEPRECATED: If true, fail when planner doesn't return helix_ql (legacy mode)
  - `intent_match_options` IntentMatchOptions: Options for intent matching in HelixDB.
    - `max_matches` integer, required: Maximum matches to return
    - `max_expansions` integer, required: Maximum expansions
    - `timeout_ms` integer, required: Timeout in milliseconds
    - `beam_width` integer, nullable: Optional: maximum neighbors to expand per relation (beam width)
    - `response_mode` string, required: Response mode (compact/full)
    - `max_evidence` integer, required: Maximum evidence items per match
    - `max_documents` integer, required: Maximum document nodes per match
    - `include_raw_properties` boolean: Include raw properties in full mode
    - `candidates_max` integer: Emit best-effort candidates when > 0
    - `candidates_min_relations` integer: Minimum relations for candidates when enabled
    - `candidates_include_exact` boolean: Whether candidates may include exact matches
    - `constraint_fuzzy` ConstraintFuzzyConfig, required: Request-provided fuzzy constraint configuration (no client defaults).
      - `constraint_candidates_k` integer, required: Top-K candidates per constrained variable
      - `constraint_min_score` number, required: Minimum weighted similarity score
      - `w_jaro_winkler` number, required: Weight for Jaro-Winkler similarity
      - `w_jaro` number, required: Weight for Jaro similarity
      - `w_levenshtein` number, required: Weight for normalized Levenshtein similarity
      - `w_contains` number, required: Weight for containment (substring) similarity
      - `vector_min_score` number, nullable: Cosine floor for vector-resolved constraints (below it the entity is not the constraint's referent)
      - `vector_margin` number, nullable: Keep only vector candidates within this distance of the best one
    - `csp` CSPConfig: CSP (Constraint Satisfaction Problem) configuration for advanced matching.
      - `use_csp` boolean: Enable CSP-based matching with domain propagation
      - `vector_k` integer: Results to fetch from vector search per constrained variable
      - `vector_k_multiplier` integer: Over-fetch multiplier for vector+fuzzy fusion
      - `propagation_budget_ms` integer: Time budget for CSP propagation phase
      - `max_propagation_rounds` integer: Maximum propagation rounds
      - `max_widening_attempts` integer: Maximum adaptive widening attempts
      - `widening_min_time_ms` integer: Minimum remaining time to attempt widening
      - `include_diagnostics` boolean: Include detailed domain diagnostics in response
      - `edge_first` boolean: Enable edge-first CSP propagation (alias-aware, scan-budgeted)
      - `allow_path_recovery` boolean: Allow bounded length-2 path recovery when direct edge support is absent
    - `query_type` string, nullable: Optional planner hint: pure_graph, pure_vector, hybrid, entity_lookup
    - `cursor` string, nullable: Optional pagination cursor for streaming large result sets
    - `page_size` integer, nullable: Optional page size for pagination

## Response `200`

Successful Response

- NLQExecuteResponse: Natural language query -> plan -> execute response.
  - `answer` NLQAnswer: The answer /nlq/execute computed from what it retrieved. Decided deterministically (no LLM): the best-scoring graph matches, else vector passages that mention every resolved anchor of the question, else no_match. Identical calls on unchanged data give the identical answer.
    - `status` 'answered' | 'no_match' | 'no_data', required
    - `source` 'graph' | 'vector', nullable
    - `text` string, required
    - `entities` string[]: Answer entities, best first (graph answers)
    - `evidence` NLQEvidence[]: What the answer rests on
      - `text` string, required
      - `source` 'graph' | 'vector', required
      - `score` number, nullable
    - `unresolved` object[]: Constraints of the question that name nothing in your memory ({variable, constraint})
  - `planner` 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
  - `executed` boolean, required: Whether intent matching was performed
  - `intent_graph` IntentGraph: IntentGraph: abstract representation of user query intent. Based on HydraPlanner paper Section 6 (End-to-End Example). This is the output of the IntentGraphBuilder stage.
    - `root` TypedVariable, required: A typed variable in the IntentGraph.
      - `name` string, required: Variable name
      - `type` string, required: Node label/type from schema
      - `constraint` string, nullable: Optional abstract constraint (e.g., 'large tech', 'recent')
    - `goals` TypedVariable[], required: Goal variables representing desired result entities
      - `name` string, required: Variable name
      - `type` string, required: Node label/type from schema
      - `constraint` string, nullable: Optional abstract constraint (e.g., 'large tech', 'recent')
    - `required_relations` RelationHole[]: Abstract relations between variables (relation holes)
      - `from_var` string, required: Source variable name
      - `to_var` string, required: Target variable name
      - `role` string, required: Abstract semantic role (e.g., 'knows', 'employed_at', 'founded')
  - `intent_matches` IntentMatchesResponse: Response from HelixDB intent matching.
    - `success` boolean, required: Whether matching succeeded
    - `matches` IntentMatch[]: Intent matches
      - `bindings` object, required: Variable to binding mapping
      - `documents` AgentBinding[]: Connected document nodes
        - `label` string, required: Node label
        - `canonical_id` string, nullable: Canonical ID
        - `entity_name` string, nullable: Entity name
      - `evidence` EvidenceItem[]: Evidence items
        - `kind` string, required: Evidence kind (context/inference/edge_context)
        - `text` string, required: Evidence text
      - `match_key` string, required: Stable identifier for deduplication
      - `raw_bindings` object, nullable: Raw binding data (full mode only)
      - `raw_documents` unknown[], nullable: Raw document data (full mode only)
        - unknown
      - `score` number, nullable: Match confidence in [0, 1]: the weakest constrained binding's resolution score (exact name 1.0, else vector/fuzzy similarity). Matches arrive best first.
    - `candidates` object[]: Best-effort candidate matches (partial subgraphs) when enabled
    - `stats` IntentMatchStats, required: Statistics for intent matching.
      - `matches_emitted` integer, required: Number of matches returned
      - `expansions` integer, required: Number of BFS expansions
      - `documents_found` integer, required: Number of documents found
      - `elapsed_ms` integer, required: Elapsed time in milliseconds
      - `warnings` string[]: Non-fatal degradations the engine applied (e.g. a planner-proposed relation whose edge type is not in this tenant's schema was dropped)
      - `constraint_resolution` object[]: Per constrained variable: {variable, node_type, constraint, candidates[{entity_name, label, aliases, score}]}. Empty candidates = the constraint names nothing visible.
      - `unverified_relations` object[]: Planner relations ({from_var, to_var, role}) the schema has no matching edge type for; any edge between the two types was accepted, so matches do not verify them.
    - `error` string, nullable: Error message if failed
  - `rag` SearchResponse: Response from semantic search.
    - `results` SearchResultItem[]
      - `id` string, required: Node ID (UUID)
      - `score` number, required: Similarity score (0-1)
      - `text` string, required: Matched text content
      - `type` string, required: Node type/label
      - `metadata` object, nullable: Node metadata. Engine-hydrated rendering keys (when available): text_source (vector|evidence|chunk|entity_name|none), entity_name, entity_type, source_chunk_id, source_document_id
      - `inferences` string[], nullable: Inference text attached to the hit's entity (additive; null when none)
    - `query_embedding_ms` integer: Time to embed query (ms)
    - `search_ms` integer: Time to search HNSW index (ms)
  - `helixdb_query` string, nullable: DEPRECATED: Legacy HelixQL query string (not used in intent matching mode)
  - `chunks` object[]: DEPRECATED: Resolved chunk contents (use intent_matches.evidence instead)
  - `unresolved_chunk_ids` string[]: DEPRECATED: Unresolved chunk IDs (not used in intent matching mode)
  - `context` object: DEPRECATED: Agent context (use intent_matches.bindings/documents instead)
  - `helixdb_result` object, nullable: DEPRECATED: Legacy HelixDB query result (use intent_matches instead)
  - `helixdb_error` string, nullable: Error message if intent matching failed
  - `nlq_status` 'ok' | 'degraded' | 'failed' | 'not_executed' | 'no_data': Outcome of retrieval. ok: executed cleanly. degraded: results returned but something was relaxed or a secondary leg failed (see degraded_reasons). failed: graph/vector retrieval failed and returned nothing (HTTP status is still 200). not_executed: plan-only request (execute=false). no_data: this tenant has no knowledge graph yet (the planner is not called).
  - `degraded_reasons` string[]: Stable codes for why nlq_status is degraded/failed: graph_unavailable, vector_unavailable, plan_unavailable, graph_relation_substituted, graph_relation_dropped, graph_relation_unverified, graph_plan_relaxed

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