---
title: "Plan and validate network link capacity for homelab workloads. Determine whether a 1G, 2.5G, 10G, or faster link can handle your concurrent streams (VMs, backups, media, iSCSI). Calculates effective bandwidth after TCP/IP overhead, total required bandwidth, utilization percentage, and remaining headroom. Flags saturation at 80% utilization and identifies whether the bottleneck is network or storage. Provides a 1TB transfer time reference and recommends the next link speed upgrade if your current link is saturated. Useful for planning NIC upgrades, switch purchases, and storage network design."
method: POST
path: "/api/network_bandwidth"
tags: ["homelab"]
---

# Plan and validate network link capacity for homelab workloads. Determine whether a 1G, 2.5G, 10G, or faster link can handle your concurrent streams (VMs, backups, media, iSCSI). Calculates effective bandwidth after TCP/IP overhead, total required bandwidth, utilization percentage, and remaining headroom. Flags saturation at 80% utilization and identifies whether the bottleneck is network or storage. Provides a 1TB transfer time reference and recommends the next link speed upgrade if your current link is saturated. Useful for planning NIC upgrades, switch purchases, and storage network design.

`POST /api/network_bandwidth`

## Request

- Base URL: `https://calc.engineer`
- URL: `https://calc.engineer/api/network_bandwidth`
- Auth: none declared

## Request body

- object
  - `link_speed_gbps` number, required: Network link speed in gigabits per second (e.g. 1, 2.5, 5, 10, 25, 40, 100)
  - `concurrent_streams` number: Number of concurrent data streams / transfers
  - `stream_bandwidth_mbps` number: Bandwidth required per stream in megabits per second
  - `protocol_overhead_pct` number: TCP/IP protocol overhead as a percentage (typically 3-5% for TCP, ~1% for UDP)
  - `storage_throughput_mbps` number: Maximum storage read/write throughput in megabits per second. If provided, checks whether storage is the bottleneck

## Response `200`

Computed result for network_bandwidth

- object
  - `result` object, required
    - `effective_bandwidth_mbps` number, required: Usable bandwidth after protocol overhead in Mbps
    - `required_bandwidth_mbps` number, required: Total bandwidth required by all streams in Mbps
    - `utilization_pct` number, required: Percentage of effective bandwidth used by all streams
    - `headroom_mbps` number, required: Remaining bandwidth after all streams (negative means oversubscribed)
    - `saturated` boolean, required: True if utilization exceeds 80% — link is effectively saturated
    - `bottleneck` string, required: Identified bottleneck: 'storage', 'network', or 'none'
    - `time_to_transfer_1tb_hours` number, required: Time to transfer 1 TB over the effective bandwidth, in hours
    - `recommended_link_speed_gbps` number, nullable, required: Suggested next link speed upgrade if saturated, null if current link is sufficient
  - `tool` string, required
  - `version` string, required
  - `computed_at` string, date-time, required
  - `chain` object, required
    - `feeds` unknown[]
      - unknown
    - `accepts_from` unknown[]
      - unknown

## Other responses

- `400`: Validation error or invalid JSON
- `404`: Tool not found

---

[API](https://skmtc.dev/calc/apis/calc-engineer-api.md) · [All operations](https://skmtc.dev/calc/apis/calc-engineer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/calc/apis/calc-engineer-api/revisions/8830480ec488?raw)