Counting page views in a Cloudflare Worker without spending your KV write budget

The constraint that bites

Every write-up of this problem starts from the same number: 1,000 KV writes a day on the free plan. Most of them stop there and conclude that a per-request counter runs out of budget by lunchtime, which is true and is not the interesting part.

The interesting part is that the limit is per namespace, not per key. Our namespace holds waitlist signups — the only thing on the site that could ever turn into money. Bolting a naive counter onto it would have produced this sequence: counter ships, traffic arrives, quota exhausts, and the very next person who types their email into the form gets a failure. Instrumentation destroying the thing it was built to measure, in exactly the place the next decision rests.

Why the three usual answers didn't fit

• Analytics Engine. The right tool. It wants a paid Workers plan.
• Durable Objects. Also the right tool — a single object with in-memory state is the textbook atomic counter. Also paid.
• A third-party script. Fine, and free ones exist, but it moves visitor data to someone else's server and most of them want a script tag we would rather not ship.

If you are already paying $5 a month, stop reading and use Analytics Engine: it is more accurate, it does not touch your KV budget, and you do not have to maintain any of what follows. This is for the case where the free tier is the constraint you are actually working inside.

The design, in one paragraph

Counts accumulate in the isolate's memory. They are flushed to KV at most every 30 minutes, or sooner if 250 views pile up. The isolate counts its own writes and refuses to exceed 48 in a day, no matter what happens — and when the cap bites, the dropped increments are reported through the API rather than swallowed. Counting happens before the response and flushing happens after it via waitUntil, so a KV outage costs you numbers, never the site.

Recording, on the hot path

export default {
  async fetch(request, env, ctx) {
    // ...API routes return before this point, so they are never counted.

    // Counting must never be able to break serving: record() only touches
    // memory, and flushKv() runs after the response.
    if (record(request, url)) {
      const flush = flushKv(env);
      if (ctx?.waitUntil) ctx.waitUntil(flush);
    }
    return env.ASSETS.fetch(request);
  },
};

const buf = {
  day: null, paths: Object.create(null), refs: Object.create(null),
  total: 0, lastFlush: 0, writesDay: null, writes: 0, dropped: 0,
};

function record(request, url) {
  if (!countable(request, url)) return false;
  const day = new Date().toISOString().slice(0, 10);
  if (buf.day !== day) {                       // new UTC day, fresh buffer
    buf.day = day;
    buf.paths = Object.create(null);
    buf.refs  = Object.create(null);
    buf.total = 0;
  }
  bump(buf.paths, normalisePath(url.pathname));
  bump(buf.refs, normaliseRef(request.headers.get('referer'), url.hostname));
  buf.total += 1;
  return true;
}

Flushing, with the cap

const FLUSH_EVERY_MS      = 30 * 60 * 1000;
const FLUSH_AT_PENDING    = 250;
const MAX_WRITES_PER_DAY  = 48;   // per isolate, hard cap

async function flushKv(env) {
  if (!env.KV || buf.total === 0) return;

  const now = Date.now();
  if (buf.total < FLUSH_AT_PENDING && now - buf.lastFlush < FLUSH_EVERY_MS) return;

  const day = buf.day;
  if (buf.writesDay !== day) { buf.writesDay = day; buf.writes = 0; buf.dropped = 0; }

  if (buf.writes >= MAX_WRITES_PER_DAY) {   // budget spent: drop, and SAY so
    buf.dropped += buf.total;
    buf.paths = Object.create(null);
    buf.refs  = Object.create(null);
    buf.total = 0;
    buf.lastFlush = now;
    return;
  }

  // Take the buffer BEFORE the await. Anything counted during the round-trip
  // lands in the next flush rather than being written twice or dropped.
  const pending = { paths: buf.paths, refs: buf.refs, total: buf.total };
  buf.paths = Object.create(null);
  buf.refs  = Object.create(null);
  buf.total = 0;
  buf.lastFlush = now;

  const key = 'traffic:' + day;
  let bucket = null;
  try { bucket = JSON.parse((await env.KV.get(key)) || 'null'); } catch { bucket = null; }
  if (!bucket || typeof bucket !== 'object') bucket = { total: 0, paths: {}, refs: {} };

  bucket.total = (bucket.total || 0) + pending.total;
  bucket.paths = mergeCounts(bucket.paths, pending.paths);
  bucket.refs  = mergeCounts(bucket.refs,  pending.refs);

  await env.KV.put(key, JSON.stringify(bucket), { expirationTtl: 90 * 24 * 3600 });
  buf.writes += 1;
}

Two details in there are worth more than the rest of the file. Swapping the buffer before the await means views arriving during the KV round-trip are neither double-counted nor lost — they simply belong to the next flush. And the day key carries a TTL, so old buckets delete themselves and you never write a cleanup job you will forget to test.

Bounding the key space, which most write-ups skip

A per-path breakdown means the stored value grows with the number of distinct paths requested — and the number of distinct paths requested is chosen by whoever is hitting you, not by you. Any scanner can invent ten thousand URLs. Two guards, both cheap:

const MAX_KEYS = 30;   // distinct paths/referrers per day, then 'other'

function bump(map, key) {
  if (map[key] === undefined && Object.keys(map).length >= MAX_KEYS) key = 'other';
  map[key] = (map[key] || 0) + 1;
}

function normalisePath(pathname) {
  let p = pathname.toLowerCase();
  if (p.length > 1 && p.endsWith('/'))  p = p.slice(0, -1);
  if (p.endsWith('.html'))              p = p.slice(0, -5);
  if (p === '/index' || p === '')       p = '/';
  // Anything long or oddly shaped is a scanner. Do not store its literal path.
  if (p.length > 48 || !/^\/[a-z0-9/_-]*$/.test(p)) return 'other';
  return p;
}

function normaliseRef(referer, selfHost) {
  if (!referer) return 'direct';
  let host;
  try { host = new URL(referer).hostname.toLowerCase(); } catch { return 'other'; }
  if (host.startsWith('www.')) host = host.slice(4);
  if (host === selfHost) return 'internal';
  if (host.length > 48 || !/^[a-z0-9.-]+$/.test(host)) return 'other';
  return host;
}

The value now tops out at 31 path keys and 31 referrer keys regardless of what anyone throws at it, and an attacker-chosen string never reaches storage. Note that normaliseRef keeps the hostname only — a full referrer URL can carry a search query, a session token or a private document path, and none of that belongs in your analytics.

Also: exclude your own API routes and static assets from counting, or your uptime probe becomes your best-performing traffic source.

function countable(request, url) {
  if (request.method !== 'GET') return false;
  if (url.pathname.startsWith('/api/')) return false;
  if (/\.(png|jpe?g|gif|svg|ico|css|js|json|xml|txt|webmanifest|woff2?)$/i
        .test(url.pathname)) return false;
  return true;
}

What it costs you

Stated here rather than discovered later, because a number with unstated error bars is worse than no number:

What it buys, in exchange: no cookies, no localStorage, no IP, no user agent, no session identifier, no timestamp finer than the calendar day. There is nothing in the stored value that could identify a visitor, which means there is nothing to leak and nothing to consent to.

What it read on day one

This shipped on the morning of 20 August 2026. The first fifteen hours of data:

{ "date": "2026-08-20", "total": 24,
  "paths": { "other": 21, "/feed": 1, "/pricing": 1, "/about": 1 },
  "refs":  { "direct": 24 } }

Twenty-four views. Every one of them direct. And the three named paths — /feed, /pricing, /about — do not exist on this site. Neither do the twenty-one bucketed into other, or they would have been named.

So the honest reading of day one is: essentially all of it is automated scanning, and the counter's first useful act was to prove that the shape of the data tells you so. A tool that reported "24 visitors today" and left it there would have been worse than no tool. If you build this, publish the referrer breakdown next to the total and treat a wall of direct as a warning rather than a result.