# Streaming Search

> Server-Sent Events streaming for real-time search results — 1 credit per call.

Source: http://localhost:3000/docs/endpoints/streaming-search

## Streaming Search: `POST /v1/search/stream`

The same search, streamed as server-sent events while engines answer. Cost: 1 credit.

```bash
curl -X POST https://api.hushsearch.io/v1/search/stream \
  -H "X-API-Key: hs_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "postgres MVCC explained",
  "num_results": 5
}'
```

**POST** `/v1/search/stream` — **1 credit per call**

Stream search results as Server-Sent Events (SSE). Results are emitted as they arrive from the search engine rather than waiting for all results to be collected.

## Request

Same body as [Web Search](http://localhost:3000/docs/endpoints/search):

```bash
curl -X POST https://api.hushsearch.io/v1/search/stream \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"query": "best vector databases 2026", "num_results": 5}'
```

## Event format

Each line is a Server-Sent Event:

```
event: result
data: {"title": "pgvector vs Pinecone", "url": "https://...", "snippet": "..."}

event: result
data: {"title": "Weaviate benchmark 2026", "url": "https://...", "snippet": "..."}

event: done
data: {"credits_used": 1, "credits_remaining": 99, "total_results": 5}
```

### Event types

| Event | Payload | Description |
|---|---|---|
| `result` | `SearchResult` | A single search result |
| `done` | credit summary | Stream complete |
| `error` | `{message}` | Stream error (credits refunded) |

## Notes

- Credits are debited upfront; refunded automatically on streaming errors.
- Use `Accept: text/event-stream` to receive the SSE stream; omitting it still works but the response may be buffered.
- Compatible with the `EventSource` API in browsers and `httpx` / `aiohttp` in Python.

## Python example

```python

with httpx.stream("POST", "https://api.hushsearch.io/v1/search/stream",
                  headers={"X-API-Key": "YOUR_API_KEY"},
                  json={"query": "vector databases"}) as r:
    for line in r.iter_lines():
        if line.startswith("data:"):
            print(line[5:])
```
