Run one KnowQL query turn

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

• X-Pinecone-Api-Version (header, string) — 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.

• ask (body, string, required) — The natural-language question
• scope (body, string[]) — Context slugs/UUIDs. New session only; pinned for the session's life. A scope may not mix work and search contexts.
• session_id (body, string) — Continue an existing session
• previous_query_id (body, string) — Continue the session this query belongs to
• workflow (body, string) — Search workflow for this turn. Ignored for work contexts, which always run the work runtime.
• system_prompt (body, string) — Instructions pinned to a new session
• guardrails (body, string) — Guardrails pinned to a new session
• shape (body, object) — JSON Schema subset for structured output; result in output_json
• model (body, 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 (body, string[]) — Ordered fallback list, tried in turn. Takes precedence over model.
• tools (body, string[]) — Tool names the turn may call. New session only; pinned for the session's life.
• stream (body, boolean) — SSE streaming. Mutually exclusive with background.
• background (body, boolean) — Fire-and-forget: 202 + in_progress query; poll GET /queries/{id}. Mutually exclusive with stream.
• timeout_seconds (body, integer) — May only LOWER the 15-minute (900s) cap
• max_steps (body, integer) — Cap the agent's tool-loop steps for this turn
• thinking_level (body, string) — Gemini reasoning depth. Default low. Gemini-backed workflows only; ignored for search_cc.
• compose (body, boolean) — Set false to skip synthesis, the same as retrieval_only.
• retrieval_only (body, boolean) — Skip synthesis; return retrieved hits in output_json
• pointers_only (body, boolean) — Skip synthesis; return just pointers in output_json
• chunks_only (body, boolean) — Retrieval-only, narrowed to chunks
• artifacts_only (body, boolean) — Retrieval-only, narrowed to artifacts
• max_retrieved (body, integer) — Cap the item count for retrieval-only turns
• max_retrieved_chars (body, integer) — Cap per-item verbatim text length for retrieval-only turns
• comparison_group (body, 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.

• 200 — The completed query turn (synchronous), or the SSE stream when stream=true
• 202 — Accepted (background); poll GET /queries/{id}
• 400 — Missing/invalid ask, mixed-kind scope, unavailable model, or stream+background together
• 404 — Scoped context, session, or previous_query_id not found
• 409 — A scoped context is not curated, a query is already in flight on the session, or a preview cap was hit
• 504 — Turn timed out (15-minute cap, or a lower timeout_seconds)