# Report JSON shape (spec_version 1)

This page summarizes the `spec_version: 1` report shape that both
`bee-check --output json` and `bee-check-web` produce. The
authoritative version lives in
[`SPEC.md`](https://github.com/ethswarm-tools/bee-check/blob/main/SPEC.md)
in the repo — this chapter mirrors it for ease of reading.

## Top level

```jsonc
{
  "reference":    "c79394...bdc36a",
  "status":       "retrievable" | "unretrievable" | "partial" | "error",
  "vantages":     [ VantageResult, ... ],
  "gateways":     [ GatewayResult, ... ],    // omitted when no --gateway
  "resolution":   Resolution,                // present when feed input
  "chunks":       [ ChunkProbe, ... ],       // present when --per-chunk
  "chunk_stats":  ChunkStats,                // present when --per-chunk
  "spec_version": 1
}
```

## Aggregate status

| status | meaning |
|--------|---------|
| `retrievable` | every vantage and gateway returned yes |
| `unretrievable` | every vantage returned no or errored |
| `partial` | at least one yes and at least one not-yes |
| `error` | every vantage errored without producing an answer |

Exit code is `0` iff at least one yes; `2` otherwise.

## VantageResult

```jsonc
{
  "bee_url":           "http://localhost:1633",
  "retrievable":       true | false | null,    // null when the call errored
  "elapsed_ms":        312,
  "error":             "...",                  // present when retrievable is null
  "overlay":           "7179...6c9a",
  "bee_version":       "2.7.2-rc1-868c1d52",
  "proximity_to_root": 3,
  "target_proximity":  5                       // present with --target-overlay
}
```

## GatewayResult

```jsonc
{
  "url":         "https://api.gateway.ethswarm.org",
  "retrievable": true | false | null,
  "elapsed_ms":  412,
  "status_code": 200,        // omitted on network error
  "error":       null
}
```

## Resolution

Present when the user supplied `feed:OWNER:TOPIC`:

```jsonc
{
  "kind":               "feed",
  "owner":              "1234...abcd",
  "topic":              "5678...beef",
  "resolved_reference": "c79394...bdc36a"
}
```

## ChunkProbe

```jsonc
{
  "address":      "1a2b3c...ef",
  "neighborhood": "1a",
  "per_vantage": {
    "http://localhost:1633": {
      "found":      true,
      "elapsed_ms": 412,
      "proximity":  4
    }
  }
}
```

## ColdDownloadResult

Present when `--cold` was used. One entry per `--bee` (probed via
`/bytes/{ref}`) and one per `--gateway` (probed via `/bzz/{ref}/`).

```jsonc
{
  "url":              "http://localhost:1633",
  "endpoint":         "/bytes/{ref}",
  "success":          true,
  "bytes_downloaded": 4096,
  "elapsed_ms":       312,
  "status_code":      200,
  "error":            null
}
```

Informational only — `cold_downloads` does NOT contribute to the
top-level `status` aggregate. Surfaces end-to-end transport
behavior independent of stewardship.

## ChunkStats

```jsonc
{
  "per_vantage": {
    "http://localhost:1633": {
      "total": 42, "found": 40, "missing": 2,
      "elapsed_p50_ms": 120, "elapsed_p95_ms": 540, "elapsed_max_ms": 800
    }
  },
  "per_neighborhood": {
    "1a": {
      "total": 10, "found": 10, "missing": 0,
      "elapsed_p50_ms": 200, "elapsed_p95_ms": 1100, "elapsed_max_ms": 1400
    }
  }
}
```

## Compatibility rules

- New fields may be added in any release without bumping
  `spec_version`. **Consumers must ignore unknown fields.**
- Renames or removals bump `spec_version`.
- The two surfaces (`bee-check` and `bee-check-web`) ship the same
  spec version at any given time.
