SignalChoose freshness for the job
A weekly creator shortlist and a live campaign dashboard have different freshness needs. Asking for a new source fetch on every page load increases collection work without necessarily improving the decision. Start by deciding how old a result can be before it stops being useful.
SignalShelf accepts 1h, 24h, or 7d as a maximum cache age. The default is 24h. The value live requests a refresh, while concurrent identical requests can share a newly collected result. These choices describe what a caller will accept; they are not a promise that a public platform exposes a metric in real time.
Read the data and its receipt
Lookup responses contain data and meta. Treat the metadata as part of the result: cache tells you whether it was a HIT, MISS or SAMPLE; fetched_at identifies when the source was collected; age_seconds expresses its current age; credits_charged reports what this request cost.
A live cache HIT is still a real previously fetched response. A SAMPLE is illustrative fixture data. They can both cost zero, but they mean different things. Analytics and research workflows should keep that distinction in storage and in the interface.
{
"meta": {
"mode": "live",
"cache": "HIT",
"credits_charged": 0,
"fetched_at": "2026-10-31T09:00:00.000Z",
"age_seconds": 1800
}
}
Illustrative metadata only; event_id and duration_ms are omitted here for clarity.Understand what changes the cache identity
The platform and resource matter, and so do the parameters that select a result. A GitHub repository list on page two is not page one. A Bluesky feed cursor selects another portion of the feed. Different result-selecting options need distinct cache entries so one customer does not receive another page by mistake.
Freshness changes whether an existing entry is acceptable, rather than the underlying identity of that entry. Equivalent default parameters should reuse the same result. A profile lookup and an Instagram media lookup use different cache namespaces even if their identifiers happen to resemble one another.
Public source results can be shared in the cache across accounts. Account balances, request history, keys and saved collections remain private account data. A free public cache hit must never become a reason to share those records.
Count successful fresh work, not optimistic attempts
A new successful live lookup costs one credit. Accepted cached responses, samples and failures cost zero. The server reserves a credit before a fresh source call and settles it only with the successful result; modeled upstream failures restore the reservation.
That customer rule does not make failed source requests free to operate. Browser time, proxy bandwidth and hosting can still be consumed before a lookup fails. A viable service must measure cost per delivered result, including unsuccessful attempts, rather than pricing only the happy path.
Concurrent identical requests are coalesced to avoid duplicate collection work. This helps with bursts of demand, but it does not turn an unlimited volume of genuinely fresh results into zero-cost work.
Retry with the collection state in mind
Respect Retry-After when the API throttles a request. Fix invalid parameters instead of retrying them, and stop fresh work when credits are exhausted. A provider failure should be visible to the user rather than quietly replaced with sample data.
A client timeout can be ambiguous: the source fetch may finish after the client disconnects. Retrying a forced-live request immediately can create another refresh. If the workflow permits it, retry with an accepted freshness window so a completed result can be reused. Bound retries and check the returned metadata.
Test the complete application path: a fresh success, a repeat hit, an upstream failure, another page and concurrent duplicates. Local simulation is good evidence for client and billing behavior in those scenarios; live source compatibility and production reliability still need separate checks.