InsightSocial APICaching
How cached answers are flagged and priced, when a repeat call is free, and how to force a fresh fetch.
Two things can make a call cheaper than its listed price. A recent answer to the same request may already sit in our shared cache, which costs 5 credits instead of the full price. And if your own account paid for the exact same call recently, the repeat costs nothing.
Neither needs setup. Both are reported on every response.
Reading the signals
| Field | Meaning |
|---|---|
cached | true when the answer came from our shared cache instead of a new fetch |
charge_reason | Why you were charged what you were: miss, shared_cache, owned, replay or no_result |
credits_used | What this call cost. Also in the X-Credits-Used header |
Rely on the body fields. There is no X-Cache header.
What each case costs
| Case | cached | charge_reason | Credits |
|---|---|---|---|
| New fetch | false | miss | The endpoint's price (metered: what it used) |
| Served from the shared cache | true | shared_cache | 5 |
| Your account already paid for this exact call inside the window | either | owned | 0 |
| Nothing found | false | no_result | 0 |
The shared cache is not tied to your account. Public data is the same for everyone, so a request someone else made moments ago can answer yours. That is why a shared-cache answer is cheap but not free: you have not paid for this data before. Once you have, owned takes over.
Owned windows
After a paid call succeeds, the same call from your account is free for a window. The same call means the same path and the same query parameters, in any order, from any key on your account. Change any parameter, including cursor, and it is a different call.
| Endpoint kind | Window |
|---|---|
| Search, trending, explore, suggestions, hashtags | 1 hour |
| Other paginated lists | 6 hours |
| Profiles, users, channels, pages, accounts | 24 hours |
| Everything else | 6 hours |
The window for each endpoint is printed on its reference page and published in /v1/endpoints as cache_ttl_seconds. It counts from your last paid call; free repeats inside it do not push it back. A free call from your 10 lifetime free calls counts as paid.
An owned repeat is still answered normally. Only the charge is zero.
Force a fresh fetch
When you need data as it is right now, send Cache-Control: no-cache, or add fresh=1 to the query string. Either skips the shared cache and is never treated as owned, so the call is always charged at the endpoint's normal price.
curl "https://api.insightsocial.app/v1/tiktok/profile?handle=khaby.lame" \
-H "x-api-key: $INSIGHTSOCIAL_API_KEY" \
-H "Cache-Control: no-cache"The same request with the query-string form:
curl "https://api.insightsocial.app/v1/tiktok/profile?handle=khaby.lame&fresh=1" \
-H "x-api-key: $INSIGHTSOCIAL_API_KEY"fresh=1 (or fresh=true) is read by us and not passed on as an endpoint parameter. Either form affects only the request it is on.
A fresh call that succeeds is a paid call, so it opens a new owned window: repeats of it without no-cache are free for that window.
When should I force a fresh fetch?
Leave it off for most work. Repeats inside the owned window are free, and a shared-cache answer is far cheaper than a new fetch. Force it only when stale data would be wrong, for example:
- a reconciliation or audit that must reflect the platform at the moment of the call;
- reading a post or profile straight after it changed;
- comparing a cached answer against a live one while debugging.