> ## Documentation Index
> Fetch the complete documentation index at: https://docs.locusmedical.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# retrieve/stream

> POST /v2/retrieve/stream — la même réponse, diffusée étape par étape en NDJSON.

`POST /v2/retrieve/stream` prend le **même corps de requête** que
[`/v2/retrieve`](/fr/capabilities/retrieve) et rend la **même payload** — mais au
fil de l'eau, une ligne JSON par étape réellement terminée.

C'est ce qui permet à une interface de montrer l'avancée **réelle** du
retrieving au lieu d'une barre qui invente sa progression. Une réponse enchaîne
plusieurs appels lourds ; une étape muette pendant ce temps-là est
indistinguable d'une étape bloquée.

```
Content-Type: application/x-ndjson
```

Chaque ligne est un objet JSON complet, séparé par `\n`. Il n'y a pas de
reconnexion à gérer : `fetch` et un lecteur de flux suffisent.

## Les lignes

| `step`         | Émise quand                                                                                 |
| -------------- | ------------------------------------------------------------------------------------------- |
| `query_maker`  | La question est qualifiée et reformulée.                                                    |
| `retrieval`    | Les deux voies ont rendu leurs unités.                                                      |
| `deliberation` | La seconde lecture est terminée (trace complète).                                           |
| `answer`       | La réponse est rédigée.                                                                     |
| `drugs`        | Les cartes médicament sont rattachées.                                                      |
| `done`         | **Ligne terminale.** `payload` porte le corps complet, identique à celui de `/v2/retrieve`. |
| `error`        | **Ligne terminale.** `detail` dit ce qui a lâché.                                           |

Avec `deliberate: true`, la boucle réflexive diffuse en plus chacun de ses tours
**sans attendre son verdict** :

| `step`               | Ce qu'il porte                                                                                                    |
| -------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `deliberation_judge` | `index`, `saw` (ce que le juge avait sous les yeux), `sufficient`, `checks`, `gaps`, la `probe` décidée, `asked`. |
| `deliberation_probe` | `index`, `modality`, `query`, `seeds`, `rationale`, `gained`, `gained_ids`.                                       |

Sans eux, l'étape reste muette pendant trois appels lourds et deux retrievings.

<Note>
  Une panne de dépendance ne peut plus lever une erreur HTTP ici : le flux a déjà
  commencé, donc elle arrive comme ligne terminale `error`. Le statut est `200`
  dès la première ligne — c'est le contenu du flux qu'il faut lire, pas le code.
</Note>

## Lire le flux

<CodeGroup>
  ```typescript TypeScript theme={null}
  const resp = await fetch("https://core.locusmedical.fr/v2/retrieve/stream", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.LOCUS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ query: "antibioprophylaxie chirurgie colorectale" }),
  });

  const reader = resp.body!.getReader();
  const decoder = new TextDecoder();
  let buffer = "";

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    buffer += decoder.decode(value, { stream: true });

    // Une ligne complète = un objet. La dernière peut être partielle : on la garde.
    const lines = buffer.split("\n");
    buffer = lines.pop() ?? "";

    for (const line of lines) {
      if (!line.trim()) continue;
      const event = JSON.parse(line);
      if (event.step === "done") console.log(event.payload.answer);
      else if (event.step === "error") throw new Error(event.detail);
      else showProgress(event.step);
    }
  }
  ```

  ```python Python theme={null}
  import httpx, json

  with httpx.stream(
      "POST",
      "https://core.locusmedical.fr/v2/retrieve/stream",
      headers={"Authorization": f"Bearer {LOCUS_API_KEY}"},
      json={"query": "antibioprophylaxie chirurgie colorectale"},
      timeout=180,
  ) as r:
      r.raise_for_status()
      for line in r.iter_lines():
          if not line:
              continue
          event = json.loads(line)
          if event["step"] == "done":
              print(event["payload"]["answer"])
          elif event["step"] == "error":
              raise RuntimeError(event["detail"])
          else:
              print("…", event["step"])
  ```

  ```bash cURL theme={null}
  curl -N -X POST https://core.locusmedical.fr/v2/retrieve/stream \
    -H "Authorization: Bearer $LOCUS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "antibioprophylaxie chirurgie colorectale"}'
  ```
</CodeGroup>

<Warning>
  Bufferisez la fin de tampon. Un morceau réseau ne tombe pas sur une frontière
  de ligne : découper naïvement sur `\n` sans conserver le reliquat coupe un
  objet JSON en deux et fait échouer le parse au hasard de la charge.
</Warning>