Cache Behavior

The use_cache parameter determines how we retrieve data. If not explicitly specified in the request, we will use the default value configured in the user's dashboard settings.

use_cache=if-present

We will first check the cache. If a cached result exists, it is returned regardless of its age, and fallback_to_cache is ignored. If no cache exists, we perform a live fetch and return that result.

use_cache=if-recent

This option costs 1 extra credit (see Credits for cost details). We will check the cache first:

• If no cache exists, we will perform a live fetch and return that result.
• If the cache exists and is less than 29 days old, the cached result is returned regardless of fallback_to_cache.
• If the cache is older than 29 days, we will attempt a live fetch:
  • If the live fetch succeeds, that result is returned.
  • If it fails, fallback_to_cache is applied:
    • on-error: return the cached value
    • never: return the live fetch failure (e.g., 404 not found, 503 fetch failed)

live_fetch=force

Setting live_fetch=force will bypass cache entirely and trigger a live fetch regardless of cache age. This costs 9 extra credits (see Credits for cost details).