Upstream Pacing

The server sits between your clients and YouTube using a single shared egress IP. One client polling in a tight loop — or fifty clients bootstrapping at once — would otherwise look like an attack to YouTube, which throttles by IP. Every request that leaves the server for an innertube endpoint therefore passes through a gate with two mechanisms.

Pacing

Outgoing innertube calls are spaced at least 250 ms apart and run at most 4 concurrently. A burst of incoming requests does not translate into a burst of outgoing ones; it becomes a queue that drains at a steady rate.

What this means for latency:

Incoming burst	Outgoing behaviour
1 request	Sent immediately (next free slot)
10 identical requests	1 sent; 9 share its response
20 distinct requests	Sent over ~5 s, up to 4 at a time

Deduplication

Concurrent requests that are byte-for-byte equivalent at the upstream level — same token, client, endpoint, apiKey, and host — collapse into a single YouTube call. Every caller receives the same response.

This is safe because polling a continuation token does not consume it: two clients racing on the same token would receive the same batch of messages anyway. Typical victims: several instances of the client library started against the same stream, or a retry racing the original request.

Two boundaries worth knowing:

• In-flight only. The moment a shared call finishes, the next identical request makes a fresh YouTube call. Nothing is cached between completed requests — sequential duplicates each hit YouTube, and the server still holds no session state.
• Shared outcomes. All callers waiting on one upstream call share its result including failures. If the shared poll turns out to be TOKEN_EXPIRED, every waiter gets 410 and each re-bootstraps independently.

Tuning

Both knobs live in apps/api/src/lib/constant.ts alongside everything else:

Constant	Default	Meaning
UPSTREAM_MIN_INTERVAL_MS	250	Minimum spacing between outgoing innertube requests
UPSTREAM_MAX_CONCURRENCY	4	Cap on concurrent outgoing innertube requests

Raising them increases throughput toward YouTube at the cost of rate-limit headroom; lowering them protects the IP further at the cost of queueing latency. Page fetches (sw.js, the popout/watch bootstrap pages) are not paced — they happen once per session and are not the hot path.