Quota and throttling

Traffic routed through FKN’s proxy and WebVPN relays is metered per connected account when one is available, otherwise per IP. Free-tier usage gets a daily volume; past it, transfers are throttled to a slower rate until the daily window resets. An active subscription lifts that throttle. cloud.quota() lets an app read the current state.

import { cloud } from '@fkn/lib'

const status = await cloud.quota()

if (status.throttled) {
  const mbps = Math.round(status.bitsPerSecond / 1_000_000)
  console.log(`Throttled to ${mbps} Mbps. Subscribe for full speed.`)
} else {
  console.log(`${status.remainingBytes} bytes left of free quota today`)
}

What you get back

const status = await cloud.quota()

status.premium         // has an active subscription
status.overQuota       // today's free-tier volume is spent
status.throttled       // transfers are rate-limited right now (over quota, not premium)
status.usedBytes       // bytes egressed through FKN relays today, saturates at limitBytes
status.limitBytes      // free-tier daily volume before throttling
status.remainingBytes  // free-tier volume left today
status.bytesPerSecond  // current effective egress rate cap
status.bitsPerSecond   // the same cap in bits per second, for display

bytesPerSecond is the rate the relays are actually clamping this user to right now: the free rate under quota, the throttled rate once over it, or the premium rate for subscribers. Reading it means you never have to hard-code the platform’s rate constants.

usedBytes saturates at limitBytes: consumption past the free-tier volume is private and is never reported, so once a user is over quota the field reads exactly limitBytes. Your app gets everything it needs for a quota meter without FKN exposing anyone’s real transfer volume, in particular a premium user’s.

This is a cloud-tier signal

Quota reflects only traffic that goes through FKN relays. Extension requests use the browser’s connection and are not included. The desktop backend is planned and does not currently handle traffic. This is why quota lives under cloud.* and has no root alias.

cloud.quota() by execution backend

All APIs below are called from browser code. The columns show which backend performs the work.

API / feature	Extension	Cloud	Desktop
quotaCloud egress only	Not available	Supported	Not available

The value updates on the order of seconds; polling every 10 to 15 seconds while a transfer is running is plenty, and the platform caches the result so frequent polls are cheap.

import { cloud } from '@fkn/lib'

// Poll while a transfer is active and surface a throttle warning
const id = setInterval(async () => {
  const status = await cloud.quota()
  if (status.throttled) {
    // show "Throttled to N Mbps - subscribe for full speed"
  }
}, 15_000)

// later
clearInterval(id)