---
title: "Stream a grounded answer (SSE)"
method: POST
path: "/org/search/stream"
tags: ["Search"]
---

# Stream a grounded answer (SSE)

`POST /org/search/stream`

## Request

- Base URL: `https://apiv2.senso.ai/api/v1`
- URL: `https://apiv2.senso.ai/api/v1/org/search/stream`
- Auth: API key in header `X-API-Key`

Like `POST /org/search`, but streams the result as Server-Sent Events: `token` events carry the answer as it is generated, a `sources` event then carries the matched chunks — each with the `kb_node_id` of its source document — and a final `done` event closes the stream. If answer generation fails to start, an `error` event is emitted instead (the HTTP status stays 200 because headers are already sent); a provider failure mid-stream ends the stream normally (`sources` + `done`) with a truncated answer. Each call consumes search credits.

## Headers

- `X-Senso-Signals` string

## Request body

- SearchRequest
  - `query` string, required: The search query. Required and non-empty; there is a maximum length.
  - `max_results` integer: Maximum results to return. Defaults to 5; values ≤ 0 fall back to 5 and values above 20 are capped at 20.
  - `content_ids` string[]: Restrict the search to these content items.
  - `require_scoped_ids` boolean: When true, `content_ids` must be non-empty — the request is rejected with 400 otherwise. Use it to guarantee a scoped search never silently widens.
  - `search_type` string: Retrieval pipeline to use. One of `hybrid` (default), `lexical`, or `vector`. Matching is case-insensitive; an empty or omitted value selects `hybrid`. Any other value is rejected with 400.
  - `neighbor_radius` integer: `/org/search/context` only. Adds up to this many chunks either side of each matched chunk to `results`, marked `inclusion_reason: "neighbor"`, so each match can be read as a passage. Defaults to 0 (matched chunks only); values outside 0–5 are rejected with 400. Total returned text is capped at about 60,000 characters, trimming the farthest neighbours first. Ignored by the other search endpoints, whose answers already include neighbouring chunks.

## Response `200`

A `text/event-stream` of SSE events: `token` (`{"token": "..."}`), then `sources` (`{"results": [...], "total_results": N, "max_results": N, "search_type": "..."}`, where each entry of `results` is a `SearchResultChunk`), then `done` (`{}`); or `error` (`{"error": "..."}`) on a post-open failure.

## Other responses

- `400`: The request was malformed — a bad path/query parameter or an invalid value.
- `401`: Missing or invalid credentials — supply a valid org API key in the `X-API-Key` header.
- `402`: The organization is out of credits or has reached its spending limit.
- `403`: The API key is authenticated but not permitted to access this resource.

---

[API](https://skmtc.dev/senso/apis/senso-org-api.md) - [All operations](https://skmtc.dev/senso/apis/senso-org-api/llms.txt) - [OpenAPI document](https://skmtc.dev/senso/apis/senso-org-api/revisions/d789b4fcbe84?raw)