SignalChoose the freshness your workflow needs
Repeated research does not always need another live fetch. SignalShelf checks whether a stored public profile is fresh enough for your request and makes the result age visible.
Four freshness options
Use freshness 1h to accept a stored profile fetched within the past hour, 24h for the past day, or 7d for the past seven days. A missing or older result triggers a new fetch. Use live to request a new fetch rather than an existing stored result. Requests for the same profile that arrive together can share the fresh result fetched during that request window.
Free hits, metered fresh results
A cache hit uses zero credits. A successful fresh profile fetch uses one credit. Failures and demo responses use zero. A zero balance can still read an eligible cached profile; a request requiring a fresh fetch needs a credit. Cache availability is not guaranteed.
Check the response metadata
meta.cache identifies HIT, MISS, or SAMPLE. meta.fetched_at reports when a live profile was retrieved, and meta.age_seconds gives its age. meta.credits_charged tells you the actual charge for that response. A sample has no real fetch timestamp and must not be treated as live research.
Understand storage and saved snapshots
The shared cache contains public profile results and accepts them for up to seven days after fetching. Expired cache entries are periodically removed. Saving a creator creates a separate snapshot in your account; it is not automatically refreshed or deleted when the shared cache expires. Fetch the creator again to see newer data, then save the updated result.
Match freshness to the task
Daily freshness often suits a shortlist review. Hourly or live requests may suit a time-sensitive check. Profile counts reflect what the source reports when fetched, and source data itself can lag. A timestamp is evidence of retrieval time, not a guarantee that the source metric changed at that moment.