Run one KnowQL query turn

curl --request POST \
  --url https://{host}/api/query \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "ask": "<string>",
  "scope": [
    "<string>"
  ],
  "session_id": "<string>",
  "previous_query_id": "<string>",
  "workflow": "<string>",
  "system_prompt": "<string>",
  "guardrails": "<string>",
  "shape": {},
  "model": "<string>",
  "models": [
    "<string>"
  ],
  "tools": [
    "<string>"
  ],
  "stream": true,
  "background": true,
  "timeout_seconds": 123,
  "max_steps": 123,
  "thinking_level": "<string>",
  "compose": true,
  "retrieval_only": true,
  "pointers_only": true,
  "chunks_only": true,
  "artifacts_only": true,
  "max_retrieved": 123,
  "max_retrieved_chars": 123,
  "comparison_group": "<string>"
}
'

import requests

url = "https://{host}/api/query"

payload = {
    "ask": "<string>",
    "scope": ["<string>"],
    "session_id": "<string>",
    "previous_query_id": "<string>",
    "workflow": "<string>",
    "system_prompt": "<string>",
    "guardrails": "<string>",
    "shape": {},
    "model": "<string>",
    "models": ["<string>"],
    "tools": ["<string>"],
    "stream": True,
    "background": True,
    "timeout_seconds": 123,
    "max_steps": 123,
    "thinking_level": "<string>",
    "compose": True,
    "retrieval_only": True,
    "pointers_only": True,
    "chunks_only": True,
    "artifacts_only": True,
    "max_retrieved": 123,
    "max_retrieved_chars": 123,
    "comparison_group": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    ask: '<string>',
    scope: ['<string>'],
    session_id: '<string>',
    previous_query_id: '<string>',
    workflow: '<string>',
    system_prompt: '<string>',
    guardrails: '<string>',
    shape: {},
    model: '<string>',
    models: ['<string>'],
    tools: ['<string>'],
    stream: true,
    background: true,
    timeout_seconds: 123,
    max_steps: 123,
    thinking_level: '<string>',
    compose: true,
    retrieval_only: true,
    pointers_only: true,
    chunks_only: true,
    artifacts_only: true,
    max_retrieved: 123,
    max_retrieved_chars: 123,
    comparison_group: '<string>'
  })
};

fetch('https://{host}/api/query', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{host}/api/query",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'ask' => '<string>',
    'scope' => [
        '<string>'
    ],
    'session_id' => '<string>',
    'previous_query_id' => '<string>',
    'workflow' => '<string>',
    'system_prompt' => '<string>',
    'guardrails' => '<string>',
    'shape' => [
        
    ],
    'model' => '<string>',
    'models' => [
        '<string>'
    ],
    'tools' => [
        '<string>'
    ],
    'stream' => true,
    'background' => true,
    'timeout_seconds' => 123,
    'max_steps' => 123,
    'thinking_level' => '<string>',
    'compose' => true,
    'retrieval_only' => true,
    'pointers_only' => true,
    'chunks_only' => true,
    'artifacts_only' => true,
    'max_retrieved' => 123,
    'max_retrieved_chars' => 123,
    'comparison_group' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{host}/api/query"

	payload := strings.NewReader("{\n  \"ask\": \"<string>\",\n  \"scope\": [\n    \"<string>\"\n  ],\n  \"session_id\": \"<string>\",\n  \"previous_query_id\": \"<string>\",\n  \"workflow\": \"<string>\",\n  \"system_prompt\": \"<string>\",\n  \"guardrails\": \"<string>\",\n  \"shape\": {},\n  \"model\": \"<string>\",\n  \"models\": [\n    \"<string>\"\n  ],\n  \"tools\": [\n    \"<string>\"\n  ],\n  \"stream\": true,\n  \"background\": true,\n  \"timeout_seconds\": 123,\n  \"max_steps\": 123,\n  \"thinking_level\": \"<string>\",\n  \"compose\": true,\n  \"retrieval_only\": true,\n  \"pointers_only\": true,\n  \"chunks_only\": true,\n  \"artifacts_only\": true,\n  \"max_retrieved\": 123,\n  \"max_retrieved_chars\": 123,\n  \"comparison_group\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{host}/api/query")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ask\": \"<string>\",\n  \"scope\": [\n    \"<string>\"\n  ],\n  \"session_id\": \"<string>\",\n  \"previous_query_id\": \"<string>\",\n  \"workflow\": \"<string>\",\n  \"system_prompt\": \"<string>\",\n  \"guardrails\": \"<string>\",\n  \"shape\": {},\n  \"model\": \"<string>\",\n  \"models\": [\n    \"<string>\"\n  ],\n  \"tools\": [\n    \"<string>\"\n  ],\n  \"stream\": true,\n  \"background\": true,\n  \"timeout_seconds\": 123,\n  \"max_steps\": 123,\n  \"thinking_level\": \"<string>\",\n  \"compose\": true,\n  \"retrieval_only\": true,\n  \"pointers_only\": true,\n  \"chunks_only\": true,\n  \"artifacts_only\": true,\n  \"max_retrieved\": 123,\n  \"max_retrieved_chars\": 123,\n  \"comparison_group\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{host}/api/query")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"ask\": \"<string>\",\n  \"scope\": [\n    \"<string>\"\n  ],\n  \"session_id\": \"<string>\",\n  \"previous_query_id\": \"<string>\",\n  \"workflow\": \"<string>\",\n  \"system_prompt\": \"<string>\",\n  \"guardrails\": \"<string>\",\n  \"shape\": {},\n  \"model\": \"<string>\",\n  \"models\": [\n    \"<string>\"\n  ],\n  \"tools\": [\n    \"<string>\"\n  ],\n  \"stream\": true,\n  \"background\": true,\n  \"timeout_seconds\": 123,\n  \"max_steps\": 123,\n  \"thinking_level\": \"<string>\",\n  \"compose\": true,\n  \"retrieval_only\": true,\n  \"pointers_only\": true,\n  \"chunks_only\": true,\n  \"artifacts_only\": true,\n  \"max_retrieved\": 123,\n  \"max_retrieved_chars\": 123,\n  \"comparison_group\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "object": "<string>",
  "session_id": "<string>",
  "created": 123,
  "status": "<string>",
  "input": [
    {
      "role": "<string>",
      "content": "<string>"
    }
  ],
  "output": [
    {
      "role": "<string>",
      "content": [
        {
          "type": "output_text",
          "text": "<string>"
        }
      ]
    }
  ],
  "citations": [
    {
      "source": "<string>",
      "section_paths": [
        [
          "<string>"
        ]
      ],
      "pages": [
        123
      ],
      "grounding": "<string>",
      "kind": "<string>"
    }
  ],
  "steps": [
    {
      "step_id": "<string>",
      "status": "<string>",
      "commentary": "<string>",
      "fns": [
        "<string>"
      ],
      "code": "<string>",
      "cum_input_tokens": 123,
      "cum_output_tokens": 123
    }
  ],
  "usage": {
    "input_tokens": 123,
    "output_tokens": 123,
    "total_tokens": 123
  },
  "runtime_ms": 123,
  "model": "<string>",
  "error": "<string>",
  "previous_query_id": "<string>",
  "comparison": [
    {
      "workflow": "<string>",
      "query_id": "<string>",
      "model": "<string>"
    }
  ],
  "feedback": {
    "rating": "<string>",
    "comment": "<string>"
  },
  "output_json": {},
  "rollup": {
    "type": "response.turn_rollup",
    "query_id": "<string>",
    "cache_read_tokens": 123,
    "cache_write_tokens": 123,
    "n_steps": 123,
    "n_tool_calls": 123,
    "by_category": {},
    "total_hits": 123,
    "duration_ms": 123
  },
  "synthesis": {
    "type": "response.synthesis",
    "query_id": "<string>",
    "status": "<string>",
    "tokens_in": 123,
    "tokens_out": 123,
    "ms": 123,
    "answer_preview": "<string>",
    "tokens_in_cached": 123,
    "tokens_in_cache_write": 123,
    "tokens_in_fresh": 123
  },
  "trace_ref": "<string>"
}

{
  "id": "<string>",
  "object": "<string>",
  "session_id": "<string>",
  "created": 123,
  "status": "<string>",
  "input": [
    {
      "role": "<string>",
      "content": "<string>"
    }
  ],
  "output": [
    {
      "role": "<string>",
      "content": [
        {
          "type": "output_text",
          "text": "<string>"
        }
      ]
    }
  ],
  "citations": [
    {
      "source": "<string>",
      "section_paths": [
        [
          "<string>"
        ]
      ],
      "pages": [
        123
      ],
      "grounding": "<string>",
      "kind": "<string>"
    }
  ],
  "steps": [
    {
      "step_id": "<string>",
      "status": "<string>",
      "commentary": "<string>",
      "fns": [
        "<string>"
      ],
      "code": "<string>",
      "cum_input_tokens": 123,
      "cum_output_tokens": 123
    }
  ],
  "usage": {
    "input_tokens": 123,
    "output_tokens": 123,
    "total_tokens": 123
  },
  "runtime_ms": 123,
  "model": "<string>",
  "error": "<string>",
  "previous_query_id": "<string>",
  "comparison": [
    {
      "workflow": "<string>",
      "query_id": "<string>",
      "model": "<string>"
    }
  ],
  "feedback": {
    "rating": "<string>",
    "comment": "<string>"
  },
  "output_json": {},
  "rollup": {
    "type": "response.turn_rollup",
    "query_id": "<string>",
    "cache_read_tokens": 123,
    "cache_write_tokens": 123,
    "n_steps": 123,
    "n_tool_calls": 123,
    "by_category": {},
    "total_hits": 123,
    "duration_ms": 123
  },
  "synthesis": {
    "type": "response.synthesis",
    "query_id": "<string>",
    "status": "<string>",
    "tokens_in": 123,
    "tokens_out": 123,
    "ms": 123,
    "answer_preview": "<string>",
    "tokens_in_cached": 123,
    "tokens_in_cache_write": 123,
    "tokens_in_fresh": 123
  },
  "trace_ref": "<string>"
}

Query

Run one KnowQL query turn

Send ask (the natural-language question) and, when starting a new session, a scope of 1–10 contexts. Continue an existing session with session_id or previous_query_id. Scoped search contexts must be curated (work contexts are queryable immediately), and a scope may not mix work and search contexts.

stream and background are mutually exclusive. With background: true the API returns 202 with an in_progress query and the client polls GET /queries/{id}. With stream: true the API emits an SSE stream whose event: names are the event type (response.created, response.step, response.output_text.delta, response.turn_rollup, response.synthesis, response.trace, and a terminal response.completed / response.failed / response.cancelled), followed by a final query event carrying the full query object. Read the answer from output[].content[].text.

POST

query

curl --request POST \
  --url https://{host}/api/query \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "ask": "<string>",
  "scope": [
    "<string>"
  ],
  "session_id": "<string>",
  "previous_query_id": "<string>",
  "workflow": "<string>",
  "system_prompt": "<string>",
  "guardrails": "<string>",
  "shape": {},
  "model": "<string>",
  "models": [
    "<string>"
  ],
  "tools": [
    "<string>"
  ],
  "stream": true,
  "background": true,
  "timeout_seconds": 123,
  "max_steps": 123,
  "thinking_level": "<string>",
  "compose": true,
  "retrieval_only": true,
  "pointers_only": true,
  "chunks_only": true,
  "artifacts_only": true,
  "max_retrieved": 123,
  "max_retrieved_chars": 123,
  "comparison_group": "<string>"
}
'

import requests

url = "https://{host}/api/query"

payload = {
    "ask": "<string>",
    "scope": ["<string>"],
    "session_id": "<string>",
    "previous_query_id": "<string>",
    "workflow": "<string>",
    "system_prompt": "<string>",
    "guardrails": "<string>",
    "shape": {},
    "model": "<string>",
    "models": ["<string>"],
    "tools": ["<string>"],
    "stream": True,
    "background": True,
    "timeout_seconds": 123,
    "max_steps": 123,
    "thinking_level": "<string>",
    "compose": True,
    "retrieval_only": True,
    "pointers_only": True,
    "chunks_only": True,
    "artifacts_only": True,
    "max_retrieved": 123,
    "max_retrieved_chars": 123,
    "comparison_group": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    ask: '<string>',
    scope: ['<string>'],
    session_id: '<string>',
    previous_query_id: '<string>',
    workflow: '<string>',
    system_prompt: '<string>',
    guardrails: '<string>',
    shape: {},
    model: '<string>',
    models: ['<string>'],
    tools: ['<string>'],
    stream: true,
    background: true,
    timeout_seconds: 123,
    max_steps: 123,
    thinking_level: '<string>',
    compose: true,
    retrieval_only: true,
    pointers_only: true,
    chunks_only: true,
    artifacts_only: true,
    max_retrieved: 123,
    max_retrieved_chars: 123,
    comparison_group: '<string>'
  })
};

fetch('https://{host}/api/query', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{host}/api/query",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'ask' => '<string>',
    'scope' => [
        '<string>'
    ],
    'session_id' => '<string>',
    'previous_query_id' => '<string>',
    'workflow' => '<string>',
    'system_prompt' => '<string>',
    'guardrails' => '<string>',
    'shape' => [
        
    ],
    'model' => '<string>',
    'models' => [
        '<string>'
    ],
    'tools' => [
        '<string>'
    ],
    'stream' => true,
    'background' => true,
    'timeout_seconds' => 123,
    'max_steps' => 123,
    'thinking_level' => '<string>',
    'compose' => true,
    'retrieval_only' => true,
    'pointers_only' => true,
    'chunks_only' => true,
    'artifacts_only' => true,
    'max_retrieved' => 123,
    'max_retrieved_chars' => 123,
    'comparison_group' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{host}/api/query"

	payload := strings.NewReader("{\n  \"ask\": \"<string>\",\n  \"scope\": [\n    \"<string>\"\n  ],\n  \"session_id\": \"<string>\",\n  \"previous_query_id\": \"<string>\",\n  \"workflow\": \"<string>\",\n  \"system_prompt\": \"<string>\",\n  \"guardrails\": \"<string>\",\n  \"shape\": {},\n  \"model\": \"<string>\",\n  \"models\": [\n    \"<string>\"\n  ],\n  \"tools\": [\n    \"<string>\"\n  ],\n  \"stream\": true,\n  \"background\": true,\n  \"timeout_seconds\": 123,\n  \"max_steps\": 123,\n  \"thinking_level\": \"<string>\",\n  \"compose\": true,\n  \"retrieval_only\": true,\n  \"pointers_only\": true,\n  \"chunks_only\": true,\n  \"artifacts_only\": true,\n  \"max_retrieved\": 123,\n  \"max_retrieved_chars\": 123,\n  \"comparison_group\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{host}/api/query")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ask\": \"<string>\",\n  \"scope\": [\n    \"<string>\"\n  ],\n  \"session_id\": \"<string>\",\n  \"previous_query_id\": \"<string>\",\n  \"workflow\": \"<string>\",\n  \"system_prompt\": \"<string>\",\n  \"guardrails\": \"<string>\",\n  \"shape\": {},\n  \"model\": \"<string>\",\n  \"models\": [\n    \"<string>\"\n  ],\n  \"tools\": [\n    \"<string>\"\n  ],\n  \"stream\": true,\n  \"background\": true,\n  \"timeout_seconds\": 123,\n  \"max_steps\": 123,\n  \"thinking_level\": \"<string>\",\n  \"compose\": true,\n  \"retrieval_only\": true,\n  \"pointers_only\": true,\n  \"chunks_only\": true,\n  \"artifacts_only\": true,\n  \"max_retrieved\": 123,\n  \"max_retrieved_chars\": 123,\n  \"comparison_group\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{host}/api/query")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"ask\": \"<string>\",\n  \"scope\": [\n    \"<string>\"\n  ],\n  \"session_id\": \"<string>\",\n  \"previous_query_id\": \"<string>\",\n  \"workflow\": \"<string>\",\n  \"system_prompt\": \"<string>\",\n  \"guardrails\": \"<string>\",\n  \"shape\": {},\n  \"model\": \"<string>\",\n  \"models\": [\n    \"<string>\"\n  ],\n  \"tools\": [\n    \"<string>\"\n  ],\n  \"stream\": true,\n  \"background\": true,\n  \"timeout_seconds\": 123,\n  \"max_steps\": 123,\n  \"thinking_level\": \"<string>\",\n  \"compose\": true,\n  \"retrieval_only\": true,\n  \"pointers_only\": true,\n  \"chunks_only\": true,\n  \"artifacts_only\": true,\n  \"max_retrieved\": 123,\n  \"max_retrieved_chars\": 123,\n  \"comparison_group\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "object": "<string>",
  "session_id": "<string>",
  "created": 123,
  "status": "<string>",
  "input": [
    {
      "role": "<string>",
      "content": "<string>"
    }
  ],
  "output": [
    {
      "role": "<string>",
      "content": [
        {
          "type": "output_text",
          "text": "<string>"
        }
      ]
    }
  ],
  "citations": [
    {
      "source": "<string>",
      "section_paths": [
        [
          "<string>"
        ]
      ],
      "pages": [
        123
      ],
      "grounding": "<string>",
      "kind": "<string>"
    }
  ],
  "steps": [
    {
      "step_id": "<string>",
      "status": "<string>",
      "commentary": "<string>",
      "fns": [
        "<string>"
      ],
      "code": "<string>",
      "cum_input_tokens": 123,
      "cum_output_tokens": 123
    }
  ],
  "usage": {
    "input_tokens": 123,
    "output_tokens": 123,
    "total_tokens": 123
  },
  "runtime_ms": 123,
  "model": "<string>",
  "error": "<string>",
  "previous_query_id": "<string>",
  "comparison": [
    {
      "workflow": "<string>",
      "query_id": "<string>",
      "model": "<string>"
    }
  ],
  "feedback": {
    "rating": "<string>",
    "comment": "<string>"
  },
  "output_json": {},
  "rollup": {
    "type": "response.turn_rollup",
    "query_id": "<string>",
    "cache_read_tokens": 123,
    "cache_write_tokens": 123,
    "n_steps": 123,
    "n_tool_calls": 123,
    "by_category": {},
    "total_hits": 123,
    "duration_ms": 123
  },
  "synthesis": {
    "type": "response.synthesis",
    "query_id": "<string>",
    "status": "<string>",
    "tokens_in": 123,
    "tokens_out": 123,
    "ms": 123,
    "answer_preview": "<string>",
    "tokens_in_cached": 123,
    "tokens_in_cache_write": 123,
    "tokens_in_fresh": 123
  },
  "trace_ref": "<string>"
}

{
  "id": "<string>",
  "object": "<string>",
  "session_id": "<string>",
  "created": 123,
  "status": "<string>",
  "input": [
    {
      "role": "<string>",
      "content": "<string>"
    }
  ],
  "output": [
    {
      "role": "<string>",
      "content": [
        {
          "type": "output_text",
          "text": "<string>"
        }
      ]
    }
  ],
  "citations": [
    {
      "source": "<string>",
      "section_paths": [
        [
          "<string>"
        ]
      ],
      "pages": [
        123
      ],
      "grounding": "<string>",
      "kind": "<string>"
    }
  ],
  "steps": [
    {
      "step_id": "<string>",
      "status": "<string>",
      "commentary": "<string>",
      "fns": [
        "<string>"
      ],
      "code": "<string>",
      "cum_input_tokens": 123,
      "cum_output_tokens": 123
    }
  ],
  "usage": {
    "input_tokens": 123,
    "output_tokens": 123,
    "total_tokens": 123
  },
  "runtime_ms": 123,
  "model": "<string>",
  "error": "<string>",
  "previous_query_id": "<string>",
  "comparison": [
    {
      "workflow": "<string>",
      "query_id": "<string>",
      "model": "<string>"
    }
  ],
  "feedback": {
    "rating": "<string>",
    "comment": "<string>"
  },
  "output_json": {},
  "rollup": {
    "type": "response.turn_rollup",
    "query_id": "<string>",
    "cache_read_tokens": 123,
    "cache_write_tokens": 123,
    "n_steps": 123,
    "n_tool_calls": 123,
    "by_category": {},
    "total_hits": 123,
    "duration_ms": 123
  },
  "synthesis": {
    "type": "response.synthesis",
    "query_id": "<string>",
    "status": "<string>",
    "tokens_in": 123,
    "tokens_out": 123,
    "ms": 123,
    "answer_preview": "<string>",
    "tokens_in_cached": 123,
    "tokens_in_cache_write": 123,
    "tokens_in_fresh": 123
  },
  "trace_ref": "<string>"
}

Authorizations

Authorization

string

header

required

Session token from POST /auth/login. Pass as Authorization: Bearer <token>. The alternative X-Pinecone-Api-Key header is also accepted for direct-key auth (used by the Nexus CLI on first contact).

Headers

X-Pinecone-Api-Version

string

default:2026-07

Date-based contract version. Omit to resolve to the Nexus default version (2026-07, the oldest served version); send unstable for the in-development surface. The resolved version is echoed back on the same header. A present-but-unrecognized value is rejected with 400 unsupported_api_version.

Body

application/json

A single KnowQL query turn. scope and the session-config fields (system_prompt, guardrails, model/models, tools) are honored only when starting a NEW session and are pinned for its life; continue an existing session with session_id or previous_query_id. The per-turn controls (workflow, shape, max_steps, thinking_level, compose, retrieval_only/pointers_only, chunks_only/artifacts_only, max_retrieved/max_retrieved_chars) ride the turn and are not pinned to the session.

ask

string

required

The natural-language question

scope

string[]

Context slugs/UUIDs. New session only; pinned for the session's life. A scope may not mix work and search contexts.

Required array length: 1 - 10 elements

session_id

string

Continue an existing session

previous_query_id

string

Continue the session this query belongs to

workflow

string

Search workflow for this turn. Legacy aliases query_search/query_sac, query_cc, query_rag are still accepted on input. Ignored for work contexts, which always run the work runtime.

system_prompt

string

Instructions pinned to a new session

guardrails

string

Guardrails pinned to a new session

shape

object

JSON Schema subset for structured output; result in output_json

model

string

provider/model

models

string[]

Ordered fallback list; takes precedence over model

tools

string[]

stream

boolean

SSE streaming. Mutually exclusive with background.

background

boolean

Fire-and-forget: 202 + in_progress query; poll GET /queries/{id}. Mutually exclusive with stream.

timeout_seconds

integer<int64>

May only LOWER the 15-minute (900s) cap

max_steps

integer<int64>

Cap the agent's tool-loop steps for this turn

thinking_level

string

Gemini reasoning depth. Default low. Gemini-backed workflows only; ignored for search_cc.

compose

boolean

false skips synthesis (alias for retrieval_only)

retrieval_only

boolean

Skip synthesis; return retrieved hits in output_json

pointers_only

boolean

Skip synthesis; return just pointers in output_json

chunks_only

boolean

Retrieval-only, narrowed to chunks

artifacts_only

boolean

Retrieval-only, narrowed to artifacts

max_retrieved

integer<int64>

Cap the item count for retrieval-only turns

max_retrieved_chars

integer<int64>

Cap per-item verbatim text length for retrieval-only turns

comparison_group

string

Client-generated id shared by the turns of one Compare run, so the preview per-project query cap treats them as a single action. The group is size-bounded server-side (max 3 turns). Omit for a normal single query.

Response

The completed query turn (synchronous), or the SSE stream when stream=true

One query turn. Read the answer from output[].content[].text.

string

required

object

string

required

session_id

string

required

created

integer<int64>

required

Unix seconds

status

string

required

input

object[]

required

The stored message array (plain-text content).

Show child attributes

output

object[]

required

Output items; assistant text is {role, content:[{type: output_text, text}]}

Show child attributes

citations

object[]

required

Show child attributes

steps

object[]

required

Show child attributes

usage

object

required

Show child attributes

runtime_ms

integer<int64>

required

model

string | null

error

string | null

previous_query_id

string | null

comparison

object[] | null

Show child attributes

feedback

object | null

Show child attributes

output_json

object | null

Present when a shape was used, or on a retrieval-only turn

rollup

object | null

Per-turn token/cache totals + tool tally (response.turn_rollup)

Show child attributes

synthesis

object | null

Token/latency of the answer completion (response.synthesis)

Show child attributes

trace_ref

string | null

Blob key of the persisted trace

APIs

Endpoints

Run one KnowQL query turn

Authorizations

Headers

Body

Response