Run one KnowQL query turn

Send ask and, on a new session, a scope of 1–10 contexts; continue an existing one with session_id or previous_query_id. Scoped search contexts must be curated, and a scope may not mix work and search contexts. Read the answer from output[].content[].text.

stream and background are mutually exclusive. background: true returns 202 with an in_progress query to poll. stream: true emits an SSE stream whose event: names are the event type (see QueryEvent), closed by a final query frame carrying the whole turn:

id: 1
event: response.created
data: {"type":"response.created","query_id":"qry_8b3d5f1a","session_id":"ses_4f9c1e2a"}

id: 2
event: response.output_text.delta
data: {"type":"response.output_text.delta","query_id":"qry_8b3d5f1a","delta":"Revenue grew 12%..."}

id: 3
event: response.completed
data: {"type":"response.completed","query_id":"qry_8b3d5f1a"}

event: query
data: {"id":"qry_8b3d5f1a","object":"query","status":"completed","output":[...]}

POST /query

Run one KnowQL query turn

cURL

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>"
}
'

200

{
  "id": "<string>",
  "object": "<string>",
  "session_id": "<string>",
  "created": 123,
  "status": "<string>",
  "input": [
    {
      "role": "<string>",
      "content": "<string>"
    }
  ],
  "output": [
    {
      "role": "<string>",
      "content": [
        {
          "type": "<string>",
          "text": "<string>"
        }
      ]
    }
  ],
  "citations": [
    {
      "source": "<string>",
      "section_paths": [
        [
          "<string>"
        ]
      ],
      "pages": [
        123
      ],
      "score": 123,
      "grounding": "<string>",
      "kind": "<string>",
      "source_path": "<string>",
      "query_id": "<string>",
      "steps": [
        "<string>"
      ],
      "artifact_name": "<string>",
      "sources": [
        "<string>"
      ]
    }
  ],
  "steps": [
    {
      "step_id": "<string>",
      "status": "<string>",
      "commentary": "<string>",
      "fns": [
        "<string>"
      ],
      "strategy": {
        "kind": "<string>",
        "fns": [
          "<string>"
        ],
        "label": "<string>",
        "scope": [
          "<string>"
        ]
      },
      "tool_calls": [
        {
          "fn": "<string>",
          "category": "<string>",
          "args": {},
          "result": "<unknown>",
          "duration_ms": 123,
          "ok": true,
          "score_space": "<string>",
          "error": "<string>"
        }
      ],
      "code": "<string>",
      "trace_truncated": {
        "truncated": true,
        "dropped_documents": 123,
        "dropped_tool_calls": 123
      },
      "cost": {
        "tokens_in": 123,
        "tokens_out": 123,
        "decide_ms": 123,
        "execute_ms": 123,
        "tokens_in_cached": 123,
        "tokens_in_cache_write": 123,
        "tokens_in_fresh": 123
      },
      "input_tokens": 123,
      "output_tokens": 123,
      "total_tokens": 123,
      "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": {},
  "max_steps": 123,
  "thinking_level": "<string>",
  "rollup": {
    "type": "<string>",
    "query_id": "<string>",
    "n_steps": 123,
    "n_tool_calls": 123,
    "by_category": {},
    "total_hits": 123,
    "duration_ms": 123,
    "cache_read_tokens": 123,
    "cache_write_tokens": 123
  },
  "synthesis": {
    "type": "<string>",
    "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

bearerAuthapiKey

Authorization · string · header · required

Session token from POST /auth/login, sent as Authorization: Bearer <token>.

Headers

X-Pinecone-Api-Version · string · default: 2026-07

Date-based contract version, echoed back on the same header. Omit for the default (2026-07); send unstable for the in-development surface. An unrecognized value is rejected with 400 unsupported_api_version.

Body

application/json

One KnowQL query turn. scope and the session-config fields are honored only when starting a NEW session and are pinned for its life; continue an existing one with session_id or previous_query_id. Every other field rides the turn and is not pinned.

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

A context slug or UUID.

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. 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

A catalog model id from GET /models, or a tier name (lite, standard, pro) to let the deployment resolve one. New session only; pinned for the session's life.

models · string[]

Ordered fallback list, tried in turn. Takes precedence over model.

A catalog model id or tier name.

tools · string[]

Tool names the turn may call. New session only; pinned for the session's life.

A tool name.

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

Set false to skip synthesis, the same as 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 a query cap counts them as one action rather than several. Where the cap applies, a group is limited to 3 turns and a fourth is refused with 409. Omit for a normal query.

Response

200

application/json

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

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

id · string · required

Turn id, qry_<uuid>.

object · string · required

Always query, so a caller can tell this document apart from a session.

session_id · string · required

The session this turn belongs to. A turn that started a new one names it here.

created · integer<int64> · required

Unix seconds

status · string · required

Where the turn is in its lifecycle.

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

What the answer was grounded in. Empty on a turn that cited nothing.

Show child attributes

steps · object[] · required

The turn's reasoning steps, reduced from its response.step events.

Show child attributes

usage · object · required

The turn's token totals. Embed and rerank bill on their own seam and are not counted here.

Show child attributes

runtime_ms · integer<int64> · required

Wall time from turn start to terminal state.

model · string | null

The model that actually answered. Null before the turn resolves one.

error · string | null

Failure detail. Set on a failed turn.

previous_query_id · string | null

The turn this one continues. Null on a session's first turn.

comparison · object[] | null

The sibling turns of the same Compare run. Null on a normal single query.

Show child attributes

feedback · object | null

Thumbs-up/down recorded on this turn. Null until a caller submits some.

Show child attributes

output_json · object | null

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

max_steps · integer<int64> | null

The agentic tool-loop step cap this turn actually ran with, whether the request set it or the deployment default supplied it.

thinking_level · string | null

The thinking level this turn actually ran at. Null on the Claude-backed search_cc, which has no equivalent knob.

rollup · Response turn rollup · object | null

End-of-turn counters. Null on a turn the runtime never closed.

Show child attributes

synthesis · Response synthesis · object | null

The answer completion's cost. Null on a turn that skipped synthesis, as retrieval-only turns do.

Show child attributes

trace_ref · string | null

Blob key of the persisted trace. Fetch the trace itself from GET /queries/{id}/trace.