Skip to content

New AI assistant answers: ChatGPT, Gemini, Copilot and AI Mode by API

SerpKite
Get API key
Docs menu / Caching

Caching

Accept a recent cached result with max_age and pay half the credits on a hit. How freshness, cache keys, X-Cache and meta.cached work.

View as Markdown

Search requests fetch the selected provider live by default. If a slightly older result is fine for your use case, set max_age to the oldest result you accept, in seconds. When SerpKite has a matching result that fresh, it returns the search result for half the search credits; include_content page reads are charged separately. Otherwise it fetches live at the normal price and stores the result for the next caller.

curl https://api.serpkite.com/v1/search \
  -H "Authorization: Bearer $SERPKITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"best espresso machine 2026","country":"us","max_age":3600}'

How it works

  1. You send a request with max_age: 3600 (one hour).
  2. SerpKite looks up a result for the same normalised request: same endpoint, query, country, language, location, device, page, filters and so on.
  3. If one exists and is younger than max_age, it is returned with X-Cache: HIT and costs 0.5× the usual credits.
  4. If not, or if it is older, the search runs live at full price with X-Cache: MISS, and the fresh result replaces the cached one.

Without max_age (or with max_age: 0) you always get a live result and it is never served from cache. The maximum is 2,592,000 seconds (30 days).

Pricing

A cache hit halves the search or webpage charge, rounded up to the next 0.001 credit. Search include_content still adds 1 credit per successfully fetched page:

Request Live Cache hit
/v1/search (1 page) 1 0.5
/v1/search with num: 100 7 3.5
/v1/autocomplete 0.5 0.25
/v1/search + include_content: 3, all pages read 4 3.5
/v1/webpage 1 0.5

The X-Credits-Used header and meta.credits_used show the actual charge. Highlights do not add a fee or change the page-content charge.

Extract and crawl accept max_age for their individual pages: each successfully read cached page costs 0.5 credit, and each live page costs 1. Their task/result envelopes differ from search. Map and monitors do not accept max_age; see Site ingestion.

Telling a hit from a miss

  • The X-Cache response header is HIT or MISS.
  • In JSON, meta.cached is true on a hit and meta.cached_at holds the time the result was fetched (ISO 8601).
{
  "meta": {
    "request_id": "req_01J8ZK4M6Q2V7",
    "credits_used": 0.5,
    "cached": true,
    "cached_at": "2026-09-29T07:12:44Z",
    "engine": "google",
    "parse_quality": "ok"
  }
}

How long results stay cached

max_age is the freshness you accept, but results also expire on their own. Current defaults:

Endpoint Kept for up to
Most endpoints 6 hours
/v1/news 30 minutes
/v1/webpage 1 hour
/v1/autocomplete 24 hours

So max_age: 86400 on /v1/search behaves like “anything from the last 6 hours”. These retention times may change; max_age is the contract.

Privacy

Every successful live result is written to the cache, whether or not the request sent max_age: max_age only decides whether you are served a cached copy. Entries are stored in memory under a SHA-256 hash of the normalised request, so the query text is never used as a key, and they expire automatically after the times above. Your identity and API key are not part of the entry. Raw HTML (include_html) is never cached. See Privacy and data retention.

When to use it

  • Agents and chatbots: popular questions repeat. max_age: 3600 cuts cost on repeated queries without users noticing.
  • Dashboards that refresh often: use a max_age a little shorter than your refresh interval.
  • Rank tracking: usually leave it off, or set it to your tracking window, so each run reflects a fresh SERP. The batch lane is the cheaper lever there.
  • News monitoring: keep max_age short; news caching is capped at 30 minutes anyway.

max_age is also honoured inside batch requests (POST /v1/batches). A batch search cache hit uses the same half-price search charge; batch and cache discounts do not multiply it to one quarter. Batch content fetches cost 0.5 credit each.

Related: Credits and billing, Response headers.

Last updated: 2026-10-04