# The stewardship probe

The core operation `bee-check` performs against every vantage is:

```http
GET /stewardship/{reference}
```

This Bee endpoint walks the manifest at `reference` and tries to
fetch every chunk through the network — using the probed Bee node as
the *requesting* peer. It returns:

```json
{ "isRetrievable": true | false }
```

`isRetrievable: true` means the probed node was able to reach every
chunk of the content through Swarm retrieval (i.e. through other
peers in the network, not just from its own local store).

## Why "from this vantage" matters

The answer is **not** a global property of the reference. It's the
answer *this specific Bee node* got when it tried. Two nodes in
different neighborhoods will commonly get different answers for the
same reference, because:

- chunks are stored close (by proximity) to their address, and
- a node retrieving a chunk has to route a request that eventually
  reaches a peer in that chunk's neighborhood.

A node in the chunk's neighborhood gets a fast local-or-near answer.
A node far from the chunk has to traverse more hops, which is more
likely to time out or hit unresponsive peers.

This is why `bee-check` is built around **multi-vantage** probing:
each `--bee` URL is a different perspective on retrievability, and
the [aggregate `partial` status](./multi-vantage.md) is meaningful in
its own right.

## Why stewardship can disagree with `/bzz`

The most common surprise:

```bash
curl http://localhost:1633/stewardship/<ref>   # {"isRetrievable":false}
curl http://localhost:1633/bzz/<ref>/          # 200 OK with content
```

Both can be true. `/bzz/{ref}/` serves the content using **whatever
path is fastest**, which typically means the node's local store if
the chunks are pinned there. `/stewardship/{ref}` deliberately
re-fetches through the **network retrieval path** to answer the
question "can a peer who doesn't have this locally actually get it?"

So if you uploaded with `swarm-deferred-upload: true` (default) and
your node hasn't yet pushed the chunks into the network, stewardship
will say *no* even though `/bzz` happily serves them. This is the
"my upload looks lost" case covered in the [Cookbook](../cookbook/lost-upload.md).

## What the timing tells you

`bee-check` records `elapsed_ms` for each vantage — wall-clock time
from issuing the request to receiving the answer. Combined with the
[per-chunk drill-down](./manifests.md) you can often distinguish:

- **Fast yes** — chunk is local or in the immediate neighborhood.
- **Slow yes** — chunk had to traverse several hops; network is
  working but the probed node isn't near the content.
- **Slow no** — request timed out walking the network; possibly a
  garbage-collected chunk or a dead neighborhood.
- **Fast no** — usually a hard error: 404 from the API, bad request,
  CORS rejection in the browser.

## See also

- [Bee API — Stewardship](https://docs.ethswarm.org/api/#tag/Stewardship) (`GET /stewardship/{ref}`, `PUT /stewardship/{ref}`)
- [Swarm docs — Retrieval protocol](https://docs.ethswarm.org/docs/concepts/protocols/retrieval-and-push-sync)

## Complement: the cold-download probe

`bee-check --cold` adds an orthogonal probe alongside stewardship:
it streams `GET /bytes/{ref}` from each Bee URL (and `GET /bzz/{ref}/`
from each gateway), counting total bytes and timing the full
transfer. Use it when stewardship and a manual `/bzz` request
disagree — the cold-download will tell you whether bytes actually
flow end-to-end, which catches HTTP-level problems (compression
issues, content-length mismatches, mid-stream errors) that the
chunk-graph walk doesn't surface.
