> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uapi.nl/llms.txt
> Use this file to discover all available pages before exploring further.

# Caching

> One header to control freshness: x-cache-ttl

Caching in uAPI is intentionally simple. You either send the `x-cache-ttl` header or you do not.

<ParamField header="x-cache-ttl" type="integer">
  Time-to-live in seconds for a successful GET response. Valid range is 0 to 3600. 0 disables caching for this request. A positive value enables caching for that many seconds.
</ParamField>

## Behavior

If you send `x-cache-ttl` with a value between 1 and 3600, uAPI may serve subsequent identical successful GET requests from your cache for that duration. If you send `x-cache-ttl: 0` or omit the header, the response is not cached for reuse.

<Info>
  Caching is isolated per API key. Other users cannot see, populate, or evict your cache.
</Info>

## Scope

Caching applies only to successful GET requests such as `/v1/extract`. Errors and non-GET endpoints are never cached.

## SDK usage

Prefer the official SDKs; they expose `x-cache-ttl` as a simple option.

<CodeGroup>
  ```python Python (usdk) theme={null}
  import os
  from uapi import uAPI

  client = uAPI(api_key=os.environ.get("UAPI_API_KEY"))

  # Cache for 600 seconds
  resp_cached = client.extract(
      url="https://example.com",
      x_cache_ttl=600,
  )

  # Disable caching for this request
  resp_nocache = client.extract(
      url="https://example.com",
      x_cache_ttl=0,
  )
  ```

  ```javascript Node.js / TypeScript (usdk-js) theme={null}
  import 'dotenv/config'
  import uAPI from 'usdk-js'

  const client = new uAPI({
    apiKey: process.env['UAPI_API_KEY'],
  })

  // Cache for 300 seconds
  const cached = await client.extract({
    url: 'https://example.com',
    xCacheTtl: 300,
  })

  // Disable caching
  const noCache = await client.extract({
    url: 'https://example.com',
    xCacheTtl: 0,
  })
  ```

  ```bash cURL (raw HTTP) theme={null}
  # Cache for 120 seconds
  curl -s "https://api.uapi.nl/v1/extract?url=https%3A%2F%2Fexample.com" \
    -H "X-API-Key: ${UAPI_API_KEY}" \
    -H "x-cache-ttl: 120"

  # Disable caching
  curl -s "https://api.uapi.nl/v1/extract?url=https%3A%2F%2Fexample.com" \
    -H "X-API-Key: ${UAPI_API_KEY}" \
    -H "x-cache-ttl: 0"
  ```
</CodeGroup>

## Practical guidance

Use `x-cache-ttl` for URLs you call frequently and can safely reuse for up to an hour. Use `0` for highly dynamic or sensitive pages. For consistent behavior across environments, always set an explicit `x-cache-ttl` rather than relying on implicit defaults.

<Warning>
  You do not need to manage or interpret internal cache headers or implementation details. The only contract surface for caching is the `x-cache-ttl` header on your request.
</Warning>