Total Clicks Alone Aren't Enough: Time-Series Lessons from a Short-Link Stats API

Building a short-link click statistics endpoint for AI Agents sounds like just a few counters—total clicks, clicks in the last 30 days, last click time. Increment on redirect, write to an in-memory map, read it back with an admin key. Ship it, watch the dashboard numbers climb, everything's fine.

Until an Agent asks a perfectly reasonable question: "Out of my 40 links, which one is dying?"

The answer: I don't know.

Totals and Timestamps Hide "Alive vs. Dead"

The root of the problem is the data structure itself. All I have are two dimensions: cumulative click count and last-click timestamp. Those two numbers sound sufficient, but in practice they can't answer any question about trends.

The original author put it precisely: one link has 900 clicks, all in January; another link has 900 clicks, evenly spread over six months. On my stats endpoint, they return exactly the same result. The former is dead, the latter is alive—but the API can't tell the difference.

"Last click time" is a form of self-deception because it only gives you an instantaneous snapshot. It can't tell you whether clicks were concentrated early on or are ongoing, and it can't distinguish "someone happened to click once yesterday" from "steady traffic every day for the past six months." In Agent-driven automation scenarios, whether a link needs replacing, whether it's still producing value, depends on rate, not total.

Adding the Time Dimension with a Ring Buffer

The solution isn't complicated, and it doesn't require Prometheus or a time-series database. The author's approach: maintain a fixed-length array of 30 integers per link, one counter per day, with lazy rotation on read.

The core logic is a single index calculation: day_index = floor(now / 86400) % 30. The current timestamp maps to a slot in the array, and reads/writes automatically land on the correct "today." Data older than 30 days is naturally overwritten, and the ring buffer needs no separate cleanup job.

The stats endpoint now returns a daily_clicks array. With that sequence of day-ordered numbers in hand, the Agent can compute rates, trends, decay curves—whatever it wants—while the server only needs to provide the raw time-series slice.

What's clever about this design is the cost: no extra infrastructure, no background rotation process, just an array and a modulo operation. For a lightweight, Agent-facing stats interface, this is about the lowest-cost way to provide a time dimension.

Ring Buffer is a fixed-capacity, circular linear data structure where the write pointer wraps back to the start after reaching the end, with new data overwriting the oldest. Its core advantage is constant space and no explicit cleanup: in this article's scenario, an array of length 30 naturally serves as a "rolling 30-day window," and the write on day 31 overwrites the slot from day 1. Compared to queues or logs, a ring buffer doesn't need to shift elements or grow capacity—reads and writes are both O(1). Choosing a length equal to the window in days and mapping indices with floor(now / 86400) % 30 is a common trick that decouples "time slots" from "physical slots": no matter how many days pass, the current day always lands in the correct array position.

Lazy Rotation is a strategy often paired with ring buffers. The traditional approach is a scheduled task at midnight each day that shifts all slots forward by one—but this requires a background process, can introduce timezone and drift issues, and wastes resources when there are no writes. Lazy rotation defers the "rotation" step to when reads/writes occur, relying on index modulo to locate slots automatically, so no timer is needed at all. The tradeoff is that you can't proactively detect that a slot is "expired," but you can compensate by combining the timestamp with a validity check at read time. This design is common in embedded systems, monitoring agents, and lightweight APIs.

Aggregate Counters Answer "How Many," Not "When"

This lesson is worth remembering for anyone building analytics capabilities for Agents. Aggregate counters are inherently only capable of answering "how many," while an Agent, once it has the data, will inevitably ask time-related questions.

"Is this still working?"—on the surface, it's asking about totals, but fundamentally it's always asking about rate. A link with a high total may have stopped producing long ago; a link with an ordinary total may be growing steadily. If the storage layer doesn't retain information from which rate can be recovered, no amount of wrapping at the endpoint can make up for it.

A single timestamp column can't solve this. It records only the last point, while rate requires the difference between at least two points, plus the time span between them. The author's advice is direct: when designing storage, make rate recoverable; if you can't, don't expect the upper layer to derive it from totals.

The difference between aggregate counters and time series is fundamentally the difference between "points" and "streams." An aggregate counter performs an irreversible reduction on each event (sum, max, update last-time), storing only the result while discarding the raw events. A time series preserves samples arranged along a time axis, allowing post-hoc computation of differences, slopes, and moving averages. This isn't a performance difference—it's an information-theoretic one: once a reduction happens, the discarded information cannot be reverse-engineered from the result.

Rate Recoverability is a practical criterion for evaluating storage design: given a piece of stored data, can you reconstruct the rate of change over any time interval after the fact? A single timestamp doesn't have this property, because it records only the last event and lacks distribution across a time span. You need at least two or more time buckets to compute Δcount / Δtime. This is also why monitoring systems generally use histograms or time buckets rather than a single cumulative value—a cumulative value can yield a rate, provided it's sampled periodically and retained.

The Prometheus-style pull model became popular precisely because it scrapes and stores timestamped samples at fixed intervals, naturally satisfying rate recovery; the ring buffer in this article can be seen as a minimalist implementation of this idea at the per-link granularity: no external TSDB, just daily-level samples within a window kept in application memory.

Default Permission Design for Agents

This stats interface is now live on the tool page at x402.freeq.one, where you can view click details broken down by day. The author notes that an admin key still controls access, and link owners use it for free—he calls it "the only sensible default I've found so far."

This detail points to a broader topic: when Agents become the primary consumers of an API, permission models need to be rethought just like data structures. Free for link owners, gated by key, is a simple pattern that aligns "who should see what" with "who is calling." Compared to a one-size-fits-all public or fully closed approach, this layered default fits multi-Agent collaboration scenarios better.

From total clicks to daily clicks, the change is small, but it determines whether the API can answer the questions Agents will actually ask.

The x402 protocol is a set of HTTP-native protocols for machine payments, named after HTTP status code 402 "Payment Required." It aims to let APIs charge per call and settle without human intervention—a typical scenario being AI Agents autonomously purchasing data or compute. The x402.freeq.one mentioned in the article is a tool service endpoint in this ecosystem. Understanding this helps clarify the "link owners free, admin key gated" point: it's not merely access control, but aligning billing and authorization units to "who owns the resource" rather than "who is calling."

Permission models for Agents differ from human-oriented models in a few key ways: first, the caller has no interactive login interface—the key is the identity; second, an Agent may represent multiple principals simultaneously (its own user, an upstream task) and needs fine-grained delegation; third, permission decisions must be machine-readable, cacheable, and low-latency. Layered defaults—for example, "resource owners free, third parties metered, admin operations require a high-privilege key"—provide a reasonable baseline without requiring a complex identity system. To prevent privilege escalation from key leakage, practice often pairs these with short-lived tokens, scope-limited API keys, and auditable call logs.

One-line Summary

Using a 30-day ring buffer to add a time dimension to AI Agent short-link stats, letting the API answer "is this link still alive?"

Paragraph Summary

The article describes a real trap encountered when building a short-link click stats endpoint for AI Agents: with only total clicks and a last-click timestamp, you can't distinguish an active link from a dead one. The author notes that two links with the same total but different time distributions return identical results on an aggregate counter, while an Agent, once it has the data, will inevitably ask about trends and rates. The solution is a ring buffer implemented as a 30-integer array, one counter per day, with lazy slot location via floor(now / 86400) % 30—no time-series database or background rotation process needed—and the endpoint returns a daily_clicks array so the Agent can compute rates itself. The article further emphasizes that aggregate counters can only answer "how many," that rate must be recoverable at the storage layer, and that a single timestamp column can't suffice; on permissions, it proposes a layered default of "link owners free, admin key gated" to fit multi-Agent collaboration scenarios.