> ## Documentation Index > Fetch the complete documentation index at: https://docs.pinecone.io/llms.txt > Use this file to discover all available pages before exploring further. # Stream a query turn's events (SSE) > The turn's events as they land — the same `type`-named events `POST /query` emits with `stream: true`, as a standalone resumable subscription. Reconnect with `Last-Event-ID` to replay from where the stream dropped. ## OpenAPI ````yaml https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_data_2026-07.oas.yaml get /queries/{id}/events openapi: 3.0.3 info: title: Nexus API description: > Nexus turns a set of sources into a queryable, self-improving knowledge base. A context is **sources + a manifest**: upload sources, **curate** them into a searchable index, then query it. The manifest, one validated JSON document, defines how the context indexes, retrieves and answers. Curate is explicit — nothing is queryable until you run it. `{slug}` accepts a context's slug or its UUID. Query with `POST /api/query`, one turn per call, and read the answer from `output[].content[].text`; multi-turn conversations are sessions. Tasks are project-owned at `/api/tasks`, not nested under contexts. contact: name: Pinecone Support url: https://support.pinecone.io email: support@pinecone.io license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0 version: 2026-07 servers: - url: https://{host}/api description: Your Nexus deployment host variables: host: default: api.example.com description: Host of your Nexus deployment. security: - bearerAuth: [] - apiKey: [] tags: - name: Auth description: Login and identity. - name: Project description: The active Pinecone project and its disclosure state. - name: Contexts description: A context is sources + a manifest. Curate it explicitly before querying. - name: Manifest description: Manifest templates and the per-context manifest. - name: Source Files description: >- Per-context source imports (upload, connector, public repo) and the source file tree. - name: Knowledge description: Read-only browse of curated knowledge (chunks + artifacts). - name: Curation description: Curate workflow trigger, curation ledger, and version-pin primitives. - name: Connectors description: >- Project-level links to external source providers (Box, ...). Linked via OAuth or an API key, then used to import source documents into a context. - name: Query description: >- The unified KnowQL Query API: run a query turn (`/query`), fetch a turn (`/queries/{id}`), inspect its trace, manage feedback, comparison flags, and multi-turn sessions (`/sessions`). - name: Tasks description: >- Top-level, project-owned task records for every workflow (optimize, curate, search, work, explore, profile, import, pack, restore, groom). - name: Task Files description: Read, list, and delete files from live or archived task containers. paths: /queries/{id}/events: get: tags: - Query summary: Stream a query turn's events (SSE) description: >- The turn's events as they land — the same `type`-named events `POST /query` emits with `stream: true`, as a standalone resumable subscription. Reconnect with `Last-Event-ID` to replay from where the stream dropped. operationId: stream_query_events parameters: - in: path name: id description: Query turn id. required: true schema: type: string style: simple - in: header name: Last-Event-ID description: >- Resume from this event seq; delivery is inclusive of the given id (re-sending the last event is harmless — clients merge steps idempotently by step_id). schema: type: string style: simple - in: header name: X-Pinecone-Api-Version description: >- 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`. schema: default: 2026-07 x-enum: - 2026-07 - unstable type: string style: simple responses: '200': description: >- SSE event stream; each `event:` name is the event `type` and `data:` is its JSON payload. content: text/event-stream: schema: $ref: '#/components/schemas/QueryStream' '404': description: Query not found components: schemas: QueryStream: description: >- Each progress frame carries an `id:` (the sequence number — send it back as `Last-Event-ID` to resume), an `event:` name equal to the QueryEvent `type`, and that event as its JSON `data:`. A final `event: query` frame closes the stream with the full Query document and no `id:`. oneOf: - $ref: '#/components/schemas/QueryEvent' - $ref: '#/components/schemas/Query' QueryEvent: title: Progress event description: >- One progress event on a turn, discriminated by `type`. Emitted as SSE frames by a streaming `POST /query` and by `GET /queries/{id}/events`. An event whose `type` this version does not know is dropped rather than ending the turn. oneOf: - $ref: '#/components/schemas/QueryCreatedEvent' - $ref: '#/components/schemas/QueryStepEvent' - $ref: '#/components/schemas/QueryOutputTextDeltaEvent' - $ref: '#/components/schemas/TurnRollup' - $ref: '#/components/schemas/QuerySynthesis' - $ref: '#/components/schemas/QueryTraceEvent' - $ref: '#/components/schemas/QueryTerminalEvent' Query: title: Query turn description: One query turn. Read the answer from `output[].content[].text`. type: object properties: id: description: Turn id, `qry_`. type: string object: description: >- Always `query`, so a caller can tell this document apart from a session. x-enum: - query type: string session_id: description: >- The session this turn belongs to. A turn that started a new one names it here. type: string model: nullable: true description: The model that actually answered. Null before the turn resolves one. type: string created: description: Unix seconds type: integer format: int64 status: description: Where the turn is in its lifecycle. x-enum: - in_progress - completed - failed - cancelled type: string error: nullable: true description: Failure detail. Set on a `failed` turn. type: string previous_query_id: nullable: true description: The turn this one continues. Null on a session's first turn. type: string comparison: nullable: true description: >- The sibling turns of the same Compare run. Null on a normal single query. type: array items: $ref: '#/components/schemas/QueryComparisonMember' feedback: nullable: true description: >- Thumbs-up/down recorded on this turn. Null until a caller submits some. type: object properties: rating: description: Thumbs up or down. x-enum: - up - down type: string comment: nullable: true description: Free-text note. Null when none was given. type: string input: description: The stored message array (plain-text `content`). type: array items: description: One message in the turn. type: object properties: role: description: Who sent the message, e.g. `user`. type: string content: description: The message text. type: string required: - role - content output: description: >- Output items; assistant text is `{role, content:[{type: output_text, text}]}` type: array items: description: One output item. type: object properties: role: description: Who produced it, e.g. `assistant`. type: string content: description: The item's content parts. type: array items: description: One content part. type: object properties: type: description: Part kind. `output_text` carries the answer. type: string text: description: The text of this part. type: string required: - type - text required: - role - content output_json: nullable: true description: Present when a shape was used, or on a retrieval-only turn type: object additionalProperties: true citations: description: What the answer was grounded in. Empty on a turn that cited nothing. type: array items: $ref: '#/components/schemas/Citation' max_steps: nullable: true description: >- The agentic tool-loop step cap this turn actually ran with, whether the request set it or the deployment default supplied it. type: integer format: int64 thinking_level: nullable: true description: >- The thinking level this turn actually ran at. Null on the Claude-backed `search_cc`, which has no equivalent knob. type: string steps: description: The turn's reasoning steps, reduced from its `response.step` events. type: array items: $ref: '#/components/schemas/QueryStep' rollup: nullable: true description: End-of-turn counters. Null on a turn the runtime never closed. type: object allOf: - title: Response turn rollup description: >- A turn's end-of-turn counters. Served both as the stored `response.turn_rollup` event, which adds `type` and `query_id`, and as the trace blob's copy, which does not. x-component-name: TurnRollup type: object properties: type: description: Event form only. x-enum: - response.turn_rollup type: string query_id: description: Event form only. type: string n_steps: description: Reasoning steps the turn ran. type: integer format: int64 n_tool_calls: description: How many calls the whole turn made. type: integer format: int64 by_category: description: Tool calls tallied by category. type: object additionalProperties: description: Calls made in that category. type: integer format: int64 total_hits: description: Retrieved items across all calls, before dedup. type: integer format: int64 duration_ms: description: Wall time for the whole turn. type: integer format: int64 cache_read_tokens: description: Input tokens served from the prompt cache. type: integer format: int64 cache_write_tokens: description: Input tokens written into the prompt cache. type: integer format: int64 synthesis: nullable: true description: >- The answer completion's cost. Null on a turn that skipped synthesis, as retrieval-only turns do. type: object allOf: - title: Response synthesis description: >- Token counts and latency for the answer completion — the final compose step, not the retrieval loop the steps describe. Served both as the stored `response.synthesis` event and as part of a turn. x-component-name: QuerySynthesis type: object properties: type: description: Event form only. x-enum: - response.synthesis type: string query_id: description: Event form only. type: string status: description: How synthesis ended, e.g. `completed`. type: string tokens_in: description: The completion's input tokens. type: integer format: int64 tokens_out: description: The completion's output tokens. type: integer format: int64 ms: description: Wall time of the completion. type: integer format: int64 answer_preview: description: >- Leading characters of the answer, for a progress display that has no full text yet. type: string tokens_in_cached: description: Input tokens served from the prompt cache. type: integer format: int64 tokens_in_cache_write: description: Input tokens written into the prompt cache. type: integer format: int64 tokens_in_fresh: description: Input tokens neither cached nor cache-written. type: integer format: int64 trace_ref: nullable: true description: >- Blob key of the persisted trace. Fetch the trace itself from `GET /queries/{id}/trace`. type: string usage: description: >- The turn's token totals. Embed and rerank bill on their own seam and are not counted here. type: object properties: input_tokens: description: Input tokens the turn billed. type: integer format: int64 output_tokens: description: Output tokens the turn billed. type: integer format: int64 total_tokens: description: Input plus output tokens. type: integer format: int64 required: - input_tokens - output_tokens - total_tokens runtime_ms: description: Wall time from turn start to terminal state. type: integer format: int64 required: - id - object - session_id - created - status - input - output - citations - steps - usage - runtime_ms QueryCreatedEvent: title: Response created description: The turn was accepted. First frame of every stream. type: object properties: type: description: Identifies the event. x-enum: - response.created type: string query_id: description: The turn that was created. type: string session_id: description: >- The session the turn runs in — the one it continued, or the one it just started. type: string QueryStepEvent: title: Response step description: >- A reasoning step started or finished. The body is the same step shape a finished turn serves in `steps[]`, since those are reduced from these events. allOf: - description: The event envelope wrapped around the step. type: object properties: type: description: Identifies the event. x-enum: - response.step type: string query_id: description: The turn the step belongs to. type: string - $ref: '#/components/schemas/QueryStep' QueryOutputTextDeltaEvent: title: Response output text delta description: >- Answer text. Delivered as one delta once the runtime reports the turn, not token by token. type: object properties: type: description: Identifies the event. x-enum: - response.output_text.delta type: string query_id: description: The turn the text belongs to. type: string delta: description: The answer text. type: string TurnRollup: title: Response turn rollup description: >- A turn's end-of-turn counters. Served both as the stored `response.turn_rollup` event, which adds `type` and `query_id`, and as the trace blob's copy, which does not. type: object properties: type: description: Event form only. x-enum: - response.turn_rollup type: string query_id: description: Event form only. type: string n_steps: description: Reasoning steps the turn ran. type: integer format: int64 n_tool_calls: description: How many calls the whole turn made. type: integer format: int64 by_category: description: Tool calls tallied by category. type: object additionalProperties: description: Calls made in that category. type: integer format: int64 total_hits: description: Retrieved items across all calls, before dedup. type: integer format: int64 duration_ms: description: Wall time for the whole turn. type: integer format: int64 cache_read_tokens: description: Input tokens served from the prompt cache. type: integer format: int64 cache_write_tokens: description: Input tokens written into the prompt cache. type: integer format: int64 QuerySynthesis: title: Response synthesis description: >- Token counts and latency for the answer completion — the final compose step, not the retrieval loop the steps describe. Served both as the stored `response.synthesis` event and as part of a turn. type: object properties: type: description: Event form only. x-enum: - response.synthesis type: string query_id: description: Event form only. type: string status: description: How synthesis ended, e.g. `completed`. type: string tokens_in: description: The completion's input tokens. type: integer format: int64 tokens_out: description: The completion's output tokens. type: integer format: int64 ms: description: Wall time of the completion. type: integer format: int64 answer_preview: description: >- Leading characters of the answer, for a progress display that has no full text yet. type: string tokens_in_cached: description: Input tokens served from the prompt cache. type: integer format: int64 tokens_in_cache_write: description: Input tokens written into the prompt cache. type: integer format: int64 tokens_in_fresh: description: Input tokens neither cached nor cache-written. type: integer format: int64 QueryTraceEvent: title: Response trace description: The turn's trace blob has landed. type: object properties: type: description: Identifies the event. x-enum: - response.trace type: string query_id: description: The turn the trace belongs to. type: string trace_ref: description: Blob key of the persisted trace. type: string QueryTerminalEvent: title: Response completed / failed / cancelled description: >- How the turn ended. The last progress frame; a final unstamped `query` frame carrying the whole turn follows it. type: object properties: type: description: Identifies the event, and which terminal state was reached. x-enum: - response.completed - response.failed - response.cancelled type: string query_id: description: The turn that ended. type: string error: description: Failure detail. Set on the failed and cancelled events only. type: string QueryComparisonMember: description: >- One sibling turn of a Compare run — the same ask answered under a different workflow or model. type: object properties: workflow: description: The workflow that turn ran. type: string query_id: description: That turn's id. Fetch it with `GET /queries/{id}`. type: string model: description: The model that answered it. type: string Citation: description: >- What a turn's answer was grounded in. Every field is optional: a search turn cites a corpus file (`source` and its pointers), a work turn the earlier turn a fact came from (`source_path`, `query_id`, `steps`, `artifact_name`). type: object properties: source: description: Path of the cited corpus file, relative to the source-tree root. type: string section_paths: description: >- Heading paths within the source, when known. One inner array per cited section, outermost heading first. type: array items: description: One heading path, outermost heading first. type: array items: description: One heading in the path. type: string pages: description: 1-based page numbers, for sources that paginate. type: array items: description: A 1-based page number. type: integer format: int64 score: description: >- Retrieval score — how well this source answered the ask. Comparable only within one turn. type: number format: double grounding: description: The quoted span the answer rests on. type: string kind: description: Which index the citation came out of, e.g. `chunk` or `artifact`. type: string source_path: description: Work contexts — path of the artifact the fact was consolidated into. type: string query_id: description: Work contexts — the earlier turn the fact was learned from. type: string steps: description: Work contexts — step ids within that earlier turn. type: array items: description: A step id within the cited turn. type: string artifact_name: description: Work contexts — name of the cited artifact. type: string sources: description: The documents a cited artifact was derived from. type: array items: description: One document the artifact was derived from. type: string QueryStep: description: >- One step of a turn's reasoning loop. `step_id`, `status`, and `commentary` are always set; the rest are reduced from whatever the step's event carried, so an absent key stays absent. type: object properties: step_id: description: >- Identifies the step within the turn. Clients merge repeated events by it. type: string status: description: How far the step has got. x-enum: - running - completed - failed type: string commentary: description: The model's own one-line account of what this step is doing. type: string fns: description: Tool functions this step called. type: array items: description: A tool function name. type: string strategy: $ref: '#/components/schemas/StepStrategy' tool_calls: description: Per-call detail for the step's tool calls. type: array items: $ref: '#/components/schemas/TraceCall' code: $ref: '#/components/schemas/StepCode' trace_truncated: $ref: '#/components/schemas/StepTruncation' cost: $ref: '#/components/schemas/StepCost' input_tokens: description: Prompt tokens billed by this one step. type: integer format: int64 output_tokens: description: Completion tokens billed by this one step. type: integer format: int64 total_tokens: description: Prompt plus completion for this one step. type: integer format: int64 cum_input_tokens: description: Turn-to-date input tokens, including this step. type: integer format: int64 cum_output_tokens: description: Turn-to-date output tokens, including this step. type: integer format: int64 required: - step_id - status - commentary StepStrategy: description: The retrieval approach the step picked. type: object properties: kind: description: Strategy family, e.g. `artifacts_first`. type: string fns: description: Tool functions the strategy calls. type: array items: description: A tool function name. type: string label: description: Display label for the strategy. type: string scope: description: Context ids the strategy searched. type: array items: description: A context id the strategy searched. type: string TraceCall: description: One tool call within a step. type: object properties: fn: description: Name of the function this call invoked. type: string category: description: >- Which family the tool belongs to, as tallied in the rollup's `by_category`. type: string args: description: >- Compact, redacted summary of the call's arguments. The key set is tool-specific and deliberately open. type: object additionalProperties: true result: description: >- Compact summary of the call's result (never the payload). The shape varies by category and is runtime-extensible. duration_ms: description: Wall time for this one call. type: integer format: int64 ok: description: Whether the call succeeded. type: boolean score_space: description: >- Which scoring space the returned scores live in, for calls that retrieve. type: string error: description: Failure detail. Set when `ok` is false. type: string StepCode: description: >- A step's generated code, capped. Either the source string alone or a `{language, source}` document. oneOf: - title: Source description: The source string alone, as later rows store it. type: string - title: Document description: The language-tagged form earlier rows store. type: object properties: language: description: Language the code is written in. type: string source: description: The code itself. type: string StepTruncation: description: What a clamp shed from an oversized step event. type: object properties: truncated: description: Whether the clamp fired at all. type: boolean dropped_documents: description: Retrieved documents shed from the event. type: integer format: int64 dropped_tool_calls: description: How many calls the clamp discarded. type: integer format: int64 StepCost: description: >- The step's incremental token and latency cost — deltas against the running turn cursor, not totals. The cache fields are tracked only on the search-as-code path. type: object properties: tokens_in: description: The step's input tokens. type: integer format: int64 tokens_out: description: The step's output tokens. type: integer format: int64 decide_ms: description: Time spent choosing what to do. type: integer format: int64 execute_ms: description: Time spent running the tool calls it chose. type: integer format: int64 tokens_in_cached: description: Input tokens served from the prompt cache. type: integer format: int64 tokens_in_cache_write: description: Input tokens written into the prompt cache. type: integer format: int64 tokens_in_fresh: description: Input tokens neither cached nor cache-written. type: integer format: int64 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Session token from `POST /auth/login`, sent as `Authorization: Bearer `. apiKey: type: apiKey in: header name: Api-Key description: Pinecone API key, accepted as an alternative to the bearer token. ````