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

:::code-group
```bash title="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>"
}'
```

```json title="200"
{
  "id": "<string>",
  "object": "<string>",
  "session_id": "<string>",
  "model": "<string>",
  "created": 123,
  "status": "<string>",
  "error": "<string>",
  "previous_query_id": "<string>",
  "comparison": [
    {
      "workflow": "<string>",
      "query_id": "<string>",
      "model": "<string>"
    }
  ],
  "feedback": {
    "rating": "<string>",
    "comment": "<string>"
  },
  "input": [
    {
      "role": "<string>",
      "content": "<string>"
    }
  ],
  "output": [
    {
      "role": "<string>",
      "content": [
        {
          "type": null,
          "text": null
        }
      ]
    }
  ],
  "output_json": {},
  "citations": [
    {
      "source": "<string>",
      "section_paths": [
        [
          null
        ]
      ],
      "pages": [
        123
      ],
      "score": 123,
      "grounding": "<string>",
      "kind": "<string>",
      "source_path": "<string>",
      "query_id": "<string>",
      "steps": [
        "<string>"
      ],
      "artifact_name": "<string>",
      "sources": [
        "<string>"
      ]
    }
  ],
  "max_steps": 123,
  "thinking_level": "<string>",
  "steps": [
    {
      "step_id": "<string>",
      "status": "<string>",
      "commentary": "<string>",
      "fns": [
        "<string>"
      ],
      "strategy": {
        "kind": "<string>",
        "fns": [
          null
        ],
        "label": "<string>",
        "scope": [
          null
        ]
      },
      "tool_calls": [
        null
      ],
      "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
    }
  ],
  "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>",
  "usage": {
    "input_tokens": 123,
    "output_tokens": 123,
    "total_tokens": 123
  },
  "runtime_ms": 123
}
```
:::

## Authorizations

- `Authorization` (header, string, required) — Bearer authentication header of the form `Bearer <token>`.

## Headers

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

## Body

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

## Response

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

## Related pages

- [Fetch one query (turn)](./data-plane-query-fetch-one-query-turn.md)
- [Cancel an in-progress query turn](./data-plane-query-cancel-an-in-progress-query-turn.md)
- [Fetch the recorded trace for a query turn](./data-plane-query-fetch-the-recorded-trace-for-a-query-turn.md)
- [Stream a query turn's events (SSE)](./data-plane-query-stream-a-query-turns-events-sse.md)
- [Record thumbs-up/down feedback on a query turn](./data-plane-query-record-thumbs-updown-feedback-on-a-query-turn.md)
- [List the selectable query models](./data-plane-query-list-the-selectable-query-models.md)
- [List project-wide query sessions (newest first)](./data-plane-query-list-project-wide-query-sessions-newest-first.md)
- [Get a session with its queries (conversation order)](./data-plane-query-get-a-session-with-its-queries-conversation-order.md)
- [Delete a session and its queries](./data-plane-query-delete-a-session-and-its-queries.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.