Polling

Polling is a client-driven way to discover changes: the client sends a request at intervals, the server answers with the state it has at that moment, and the client repeats the request later. It is not a push channel. The server never needs to remember that a particular browser is waiting, so each request can be served by an ordinary stateless HTTP endpoint behind the gateways, load balancers, authentication layers and monitoring you already run.

The mental model is a person refreshing a page on a timer. Nothing about the exchange is special: request, response, wait, request again. Every property of polling follows from the wait. The wait sets how stale the screen can be, the number of clients divided by the wait sets how much traffic the service absorbs, and the fact that the server holds no per-client state is why polling survives deploys, load balancer reshuffles and flaky networks so well.

Take an order tracking screen that shows PREPARING, DISPATCHED and DELIVERED. The browser requests GET /orders/847/status every five seconds. If the status changes just after a poll, the user will not see it for almost five seconds. That is not a defect; it is the freshness bound the interval imposes, assuming timely responses and no failed requests. Polling trades request volume for an acceptable delay, and the whole design problem is choosing that trade deliberately.

One more consequence is easy to miss. A poll returns the current state, not the history. If the order goes PREPARING → DISPATCHED → DELIVERED between two polls, the client sees only DELIVERED. That is fine for a status badge and wrong for something like a notification feed, where every item matters; there the poll should carry a cursor (for example GET /notifications?after=8841) so that one response returns everything missed since the last one. The cursor-based catch-up is the same idea that makes Server-Sent Events recoverable.

Polling is a good fit for administrative dashboards, job status pages, inventory summaries and notifications that can tolerate seconds of delay. It turns wasteful when millions of clients poll often for data that rarely changes, and it is the wrong tool when the product needs sub-second updates.

A useful implementation starts with the server's response contract. The endpoint returns a stable identifier, the current state, and a version or update timestamp the client can compare. The version matters more than it looks: it is what lets the client ignore stale responses and what lets the server issue a cheap validator later.

GET /orders/847/status HTTP/1.1
Host: api.example.com
Cookie: session=<opaque-session-id>

HTTP/1.1 200 OK
Content-Type: application/json
ETag: "order-847-v19"
Cache-Control: private, no-cache

{"order_id":"847","status":"DISPATCHED","version":19}

The client stores the state and its version, waits for the next interval and asks again. Around that simple loop it still has to handle network failures, authentication expiry, tab suspension and overlapping responses. The server, for its part, authorizes every request. A session that was valid for the first poll is not a standing permission: the order may have been reassigned, the token may have expired, the user may have signed out in another tab. Treat each poll as an independent authenticated request, because that is what it is.

The sequence is request → response → wait → next request. It is not request → wait while the server watches for a change; that second shape is long polling, which holds the request open and has its own failure modes. In plain polling the server answers immediately, even if the answer is “nothing new”.

Slide the change time in Figure 1 and watch the response lane. Polls that find the same version are answered with 304 Not Modified (covered below); the first poll after the change is the only one after the first that carries a body. With a change at 6 seconds the poll at 10 seconds sees it, four seconds late. A change at 5.1 seconds would wait almost the full five, and one at 9.9 seconds would be seen almost at once. Freshness depends on when the change occurs relative to the next successful poll, which is why a failed request quietly adds a whole interval to the delay.

Let N be the number of active clients and T the interval in seconds. If clients poll continuously and their requests are spread evenly, the average request rate is approximately:

requests_per_second ≈ N / T

For 100,000 clients polling every five seconds the service receives roughly 20,000 requests per second even if no order changes. At a 30-second interval that drops to about 3,333 requests per second. The estimate leaves out retries, start-up bursts and any other endpoints the same page polls, and it assumes every client is active. It is an arrival rate, not a CPU or database cost: a cached status read may be nearly free, while a join-heavy query behind the same endpoint can saturate a database at a tenth of that rate.

Arrival rate also determines concurrency. By Little's law the average number of requests in flight is the arrival rate times the average latency, so 20,000 requests per second at 50 ms is about 1,000 requests in flight, and the same rate at 500 ms is about 10,000. Latency that creeps up under load therefore raises concurrency, which is one reason a polling fleet can tip from healthy to overloaded quickly.

The delay side is simpler. If changes arrive at times that are uniform relative to a fixed poll schedule, the expected detection delay is about T / 2 and the worst case is just under T, both before network and processing latency. Real traffic is not uniform: background tabs throttle timers, reconnect storms bunch requests together, and failed requests stretch the effective interval, so measured delay is usually worse than the formula.

The last readout in Figure 2 is the one that tends to change decisions. If a client's order changes every five minutes (300 seconds) and it polls every five seconds, it makes 60 requests per change, so 59 of every 60 polls (about 98%) return the state it already has. Polling more often makes that ratio worse while shaving only a couple of seconds off the average delay. Polling less often than changes occur does the opposite: several changes collapse into one poll and the client never sees the intermediate states.

Do not pick the interval from a vague “real-time” label. Start from acceptable staleness: is 30 seconds fine for a batch export, five seconds fine for a delivery update, or is 100 milliseconds genuinely needed for collaborative cursor movement? Then compute the request volume and what it costs. If the answer at the required freshness is more traffic than the backend can sustain, that is the signal to look at long polling or SSE, not to squeeze the interval.

Why a fixed timer creates traffic waves

A fixed five-second timer looks harmless until a release or a live event brings hundreds of thousands of clients to the page at once. They all poll at seconds 0, 5, 10 and 15, and the server sees a wall of requests followed by silence. Averages hide this completely: the mean is still N / T, but capacity has to be sized for the peak.

Two mechanisms fix it, and they do different jobs. A random initial delay spreads a crowd that starts together across the whole period (the middle option in Figure 3). Per-cycle jitter randomizes each wait so that clients that happened to align drift apart; on its own it does not remove the first spike (the last option), it only dissolves the later ones. Use both. Neither lowers the long-run average rate: jitter with a mean factor of 1.0 leaves it at N / T, and it only changes if you also change the mean interval.

Schedule the next poll after the previous one finishes

For a single browser, schedule the next poll after the previous request completes. A naïve setInterval() starts a new request on every tick whether or not the last one returned, so when latency exceeds the interval you get overlapping requests, extra work on a server that is already slow, and responses that arrive out of order.

Chaining has a cost worth stating: the effective period becomes latency plus wait, so a 7-second response and a 5-second wait give a poll every 12 seconds. That is the right failure mode. Under strain the client polls slower rather than piling on.

A poll loop that handles failure

The code below is the loop most pages need. Each branch of the response handling decides two things: what to do with the result, and how long to wait. The diagram below shows the same decisions.

// Browser JavaScript. Call startPolling() once the page has rendered its first state.
const BASE_MS = 5000;
const MAX_MS = 60000;
const MAX_RETRY_AFTER_MS = 300000;
const TERMINAL = new Set(['DELIVERED', 'CANCELLED']);

let running = false;
let finished = false; // terminal state, auth failure or unmount: never restart
let controller = null;
let timer = null;
let delayMs = BASE_MS;
let lastVersion = -1;

function schedule(ms) {
  if (!running) return;
  clearTimeout(timer);
  const jitter = 0.8 + Math.random() * 0.4; // +/-20 %, mean 1.0
  timer = setTimeout(pollOrder, ms * jitter);
}

function parseRetryAfter(value) {
  if (!value) return null;
  const seconds = Number(value);
  if (Number.isFinite(seconds)) return Math.max(0, seconds) * 1000;
  const at = Date.parse(value); // HTTP-date form
  return Number.isNaN(at) ? null : Math.max(0, at - Date.now());
}

function backOff() {
  delayMs = Math.min(delayMs * 2, MAX_MS);
}

async function pollOrder() {
  if (!running) return;
  const mine = (controller = new AbortController());
  let waitMs = delayMs;
  try {
    const response = await fetch('/orders/847/status', {
      signal: mine.signal,
      credentials: 'include',
      cache: 'no-store',
    });
    if ([401, 403, 404].includes(response.status)) {
      stopPolling(); // hand control to the auth flow or the "not found" UI
      return;
    }
    if (response.status === 429 || response.status === 503) {
      backOff();
      const retryAfterMs = parseRetryAfter(response.headers.get('Retry-After'));
      waitMs = Math.min(Math.max(delayMs, retryAfterMs ?? 0), MAX_RETRY_AFTER_MS);
    } else if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    } else {
      const next = await response.json();
      if (next.version > lastVersion) { // compare versions, not arrival order
        lastVersion = next.version;
        render(next);
      }
      if (TERMINAL.has(next.status)) {
        stopPolling();
        return;
      }
      delayMs = BASE_MS;
      waitMs = delayMs;
    }
  } catch (error) {
    if (error.name === 'AbortError') return;
    backOff();
    waitMs = delayMs;
  } finally {
    if (controller === mine) schedule(waitMs); // a newer request owns the timer
  }
}

function startPolling() {
  running = true;
  finished = false;
  delayMs = BASE_MS;
  timer = setTimeout(pollOrder, Math.random() * BASE_MS); // spread first polls
}

function stopPolling() {
  running = false;
  finished = true;
  clearTimeout(timer);
  controller?.abort();
}

A few details in the loop are deliberate. The jitter is applied when scheduling, so every path through the loop gets it, including backoff. A transient failure doubles the delay up to a cap of 60 seconds, and any success resets it to the base interval. 401, 403 and 404 end the loop because retrying a rejected credential or a missing resource every few seconds only adds load and noise; control passes to the sign-in flow or the not-found UI, which restarts polling after it succeeds. Retry-After is honored when present and is allowed to exceed the 60-second cap, within a sanity limit of five minutes. The mine handle makes sure that a request aborted by pausing cannot schedule a second timer behind the one that replaced it. And a failed fetch is never evidence that the state did not change; it only means the client does not know.

This is still a first version. A production client adds the initial render, cleanup when the component unmounts, tab visibility handling (below) and, if the server sends one, a bounded use of the suggested delay. For the general shape of retry delays and why the jitter is multiplicative, see Retry & Backoff.

Downloading identical JSON on every poll wastes bandwidth. If the server supports validators, the client sends If-None-Match with the last ETag it saw. When the selected representation has not changed, the server can answer 304 Not Modified with no body. That reduces transfer size, but it does not eliminate the HTTP request, and it does not eliminate the database or cache lookup the server needs in order to know the validator is still current.

GET /orders/847/status HTTP/1.1
If-None-Match: "order-847-v19"

HTTP/1.1 304 Not Modified
ETag: "order-847-v19"

Read Figure 6 from the database lane. Every poll, conditional or not, ends in a lookup. A 304 only removes the serialization and the body bytes from the return trip. The page is a good place for the following arithmetic. Assume the 53-byte body from the earlier trace and, for illustration, about 700 bytes of request and response headers once cookies and tracking headers are counted. At 20,000 requests per second that is roughly 15 MB/s, about 120 Mbit/s, with bodies; a 304 on every poll removes only about 1 MB/s of it, around 7%. Conditional requests pay off when bodies are large, not when they are tiny, and the saving never touches request termination, authentication or the lookup.

Making the validator honest

A meaningful validator changes whenever the response representation changes. The simplest way to guarantee that is a version column that every write increments in the same statement, and an ETag built from it. If the body also includes a derived field such as an estimated arrival time, that field must be covered by the version or by the validator, otherwise clients will keep receiving 304 for a body that would now differ. Two more details: If-None-Match uses weak comparison, so a W/ prefix must not break the match, and a proxy that recompresses responses may turn a strong ETag into a weak one.

// Node/Express. requireAuth sets req.user; db is a node-postgres style pool.
const express = require('express');
const app = express();
app.set('etag', false); // we compute the validator ourselves from the version column

// Weak comparison, as If-None-Match requires: ignore a W/ prefix, accept "*" and comma-separated lists.
function matchesIfNoneMatch(header, etag) {
  if (!header) return false;
  if (header.trim() === '*') return true;
  return header.split(',').some((tag) => tag.trim().replace(/^W\//, '') === etag);
}

app.get('/orders/:id/status', requireAuth, async (req, res) => {
  const id = Number(req.params.id);
  if (!Number.isSafeInteger(id)) return res.status(400).end();

  // Cheap point read that also enforces ownership: someone else's order looks like a missing one.
  const { rows } = await db.query(
    'SELECT status, version FROM orders WHERE id = $1 AND customer_id = $2',
    [id, req.user.id],
  );
  if (rows.length === 0) return res.status(404).end();

  const etag = `"order-${id}-v${rows[0].version}"`;
  res.set({ ETag: etag, 'Cache-Control': 'private, no-cache' });
  if (matchesIfNoneMatch(req.get('If-None-Match'), etag)) return res.status(304).end();

  res.json({ order_id: String(id), status: rows[0].status, version: rows[0].version });
});

-- PostgreSQL. Every write that changes the representation bumps the version, in the same statement.
UPDATE orders
   SET status = 'DISPATCHED', version = version + 1, updated_at = now()
 WHERE id = 847 AND customer_id = 1203
RETURNING status, version;

-- Optional hot-path cache (redis-cli). Write it after the commit; the TTL bounds how long a missed
-- update can keep an old validator alive. The cached value must still be checked against the caller.
SET order:847:status '{"status":"DISPATCHED","version":19,"customer_id":1203}' EX 60

The handler reads two columns by primary key and an owner id, which keeps ownership enforcement and validation in one cheap query. If computing the ETag required the same expensive aggregation that builds the body, the saving would be mostly network bytes, and the better fix would be a precomputed version or a cache in front of the aggregation.

Caching headers and who may store the response

The cache policy has to respect user-specific authorization, and a shared cache must never be allowed to hand one customer's order to another. Cache-Control: private, no-cache allows the browser's own cache to store the response but requires revalidation before each reuse. no-store forbids storing it at all and is the right choice for sensitive data. Conditional requests help only if both sides implement validator handling correctly.

The browser adds a wrinkle. With the default fetch cache mode and a response that carries an ETag and no-cache, the browser revalidates for you: it sends If-None-Match, receives the 304, and hands your script a normal 200 built from the cached body. The network panel shows a 304; your code never does. That is convenient, and it also means you cannot count 304s from JavaScript or react to them. If you set If-None-Match yourself, per the Fetch standard the browser stops managing the cache for that request and the 304 reaches your code. The client below does that on purpose, so it can skip rendering and tune the delay.

// Three edits to pollOrder() above. Merge them; they are fragments, not a second program.

// 1. State, next to lastVersion:
let etag = null;

// 2. Send the validator. Setting If-None-Match yourself means the response reaches your code as a real 304.
const response = await fetch('/orders/847/status', {
  headers: etag ? { 'If-None-Match': etag } : {},
  signal: mine.signal,
  credentials: 'include',
  cache: 'no-store',
});

// 3a. Before the 429/503 branch: unchanged, nothing to render, back to the base interval.
if (response.status === 304) {
  delayMs = BASE_MS;
  waitMs = delayMs;
} else if (response.status === 429 || response.status === 503) {
  /* ...as before... */
}

// 3b. Where a newer body is applied, keep its validator with it:
if (next.version > lastVersion) {
  lastVersion = next.version;
  etag = response.headers.get('ETag'); // cross-origin: the API must send Access-Control-Expose-Headers: ETag
  render(next);
}

Match the interval to what the user is doing

A job progress page can poll every two seconds while the job runs and stop as soon as the state is terminal, which the loop above already does for DELIVERED. A dashboard can poll every five seconds while visible and once a minute while backgrounded, or suspend entirely and refresh on focus. Browser background timers are throttled (Chromium-based browsers, for example, align hidden-tab timers to roughly once per second and may limit them further after a tab has been hidden for a while, with details that vary by browser and version), so never promise exact intervals.

The server can take part too. If the response includes a suggested poll_after_ms, the client uses it within bounds it controls. This gives the backend a knob: a long-running job might advertise 2,000, an idle dashboard 30,000, and an overloaded service a larger value that sheds load without rejecting anyone. The bounds matter, because a buggy or hostile value must not turn a poller into a flood or silence it for a day.

// Replaces "delayMs = BASE_MS" in the 200 branch of pollOrder().
const hint = Number(next.poll_after_ms);
delayMs = Number.isFinite(hint) ? Math.min(Math.max(hint, 1000), MAX_MS) : BASE_MS;
waitMs = delayMs;

// Pause while the tab is hidden, refresh soon after it returns. Uses the variables from the loop above.
function onVisibilityChange() {
  if (document.hidden) {
    running = false; // no timer, no request in flight
    clearTimeout(timer);
    controller?.abort();
  } else if (!running && !finished) {
    running = true;
    delayMs = BASE_MS;
    timer = setTimeout(pollOrder, Math.random() * 1000);
  }
}
document.addEventListener('visibilitychange', onVisibilityChange);

// On unmount: stopPolling(); document.removeEventListener('visibilitychange', onVisibilityChange);

That last point generalizes. If the user closes the page, cancel outstanding work. When the page reopens, fetch the current state; do not try to reconstruct the polls that would have happened in between.

Backoff for failures

Transient network failures should produce bounded exponential backoff with jitter, as in Figure 7. 429 and 503 may carry Retry-After, either as a number of seconds or as an HTTP date, and a polite client honors it when feasible. Permanent 401/403 failures should not be retried on a timer indefinitely. The cap is a trade: too high and the page stays stale long after the outage ends, too low and a recovering service meets the whole fleet at once. Jitter applied after the cap is what stops clients that failed together from retrying together. Rate limits on the server side are the counterpart of this discipline; see Rate Limiting.

Discard older responses

If the response is versioned, reject an older response that arrives after a newer one. This matters when more than one component, tab or in-flight request fetches the same resource: a refresh button, a retry, or a service worker can each produce an answer that was correct when sent and is wrong by the time it lands. Comparing versions makes the rule trivial. Comparing arrival order cannot.

The version must be monotonic per resource and come from the server; a client-side timestamp or a response counter is not a substitute. With a single serialized loop per tab the situation is rarer, but a user interaction that triggers an out-of-band refresh recreates it immediately.

Total cost has layers: request termination at the edge, authentication checks, API execution, database reads, serialization and network bytes. Figure 9 marks which of those a 304 avoids. At 20,000 requests per second the expensive part is often a database query run on every unchanged poll, so most of the work is in making the unchanged case cheap.

Cache stable status fields, prefer point lookups by primary key, avoid joins on the hot path, and consider read replicas where the freshness budget allows; the replica lag is then part of staleness, and the version check must come from the same source as the body or the ETag will lie. Coalesce identical work only when authorization and cache keys are correct, because the most expensive polling bugs are the ones that serve one user's data to another.

Where the data is not personalized (a public job page, a status board), a short Cache-Control: public, max-age=2 lets a CDN absorb most polls, subject to your CDN's behavior and how it collapses simultaneous misses. For personalized endpoints that option is off the table, so the lookup must be cheap by design. If the service is overloaded despite all of this, shed work at the edge in a controlled way (load shedding) and let Retry-After or poll_after_ms slow the clients down.

What to monitor

Track both the load and the experience; a dashboard with healthy API latency can still feel stale because the interval is long.

• Active polling clients, and requests per second against the N / T you expect.
• Conditional-hit ratio (304 over total) and average response size.
• p95 and p99 latency of the status endpoint, and the database or cache query rate behind it.
• Retry rate, plus the rate of 429 and 503 responses, which tell you clients are already being refused.
• Observed staleness: the age of the state at the moment a client renders it, measured from the server-side update time so client clock skew does not distort it.

Polling is attractive when updates are infrequent, clients are heterogeneous, operational simplicity matters and a few seconds of staleness are acceptable. It is also a robust fallback when long-lived connections are blocked or cut by intermediaries, which is why many real-time stacks keep a polling path even when they prefer another transport. An order status screen that changes every few minutes is the textbook case: the polling endpoint is a plain cached read, it is trivial to debug with curl, and it needs no connection state in the server.

Resist upgrading to WebSockets merely because a UI contains changing numbers. The more useful questions are whether the product needs server-initiated delivery, how many clients stay connected at once, and what recovery has to look like after a disconnect. If the answer is that updates must arrive within a second or two for a large audience, hold the request open with long polling or stream one-way events with SSE. If it is that a few seconds is fine, make the unchanged poll cheap, add jitter and backoff, and spend the engineering time elsewhere.

Four signals indicate that a persistent channel is worth its operating cost. Direction: if only the server has news, use SSE; if the client also sends frequent messages over the same session, a WebSocket is the two-way option. Frequency against interval: when changes arrive faster than you would be willing to poll, or most polls come back unchanged, you are paying for requests that carry nothing. Client count: a persistent connection costs memory and a file descriptor per client while idle, whereas a poll costs nothing between requests, so the saving only appears when the request volume N / T is large enough to outweigh that. Network constraints: proxies and load balancers with short idle timeouts or response buffering can break long-lived connections, and if you cannot change them, polling stays as the dependable path.

A "last seen" or online badge is often implemented by polling, either by the client asking for a status or by a heartbeat that refreshes a timestamp or expiring key. Remember that presence is a state model (who counts as online, for how long after the last signal, what happens on disconnect), not a transport: polling, SSE or WebSockets can all carry it, and a polled "last seen" value is only as fresh as the interval.