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 in the repo — this chapter mirrors it for ease of reading.

Top level

{
  "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

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

VantageResult

{
  "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

{
  "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:

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

ChunkProbe

{
  "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}/).

{
  "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

{
  "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.