InsightSocial APICaching
How cached answers are flagged and priced, and how to force a fresh fetch.
One thing 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 2 credits instead of the full price. It needs no setup and is reported on every response.
Repeating a call is charged like the first time. A repeat can return newer data, so it is a new call.
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, replay, no_result or dry_run |
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 | 2 |
| 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.
If you need the same data more than once, store the first response on your side instead of calling again.
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, 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.
When should I force a fresh fetch?
Leave it off for most work. 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.