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

# Caching

> How DomShot caching works

## Caching

DomShot caches screenshots to reduce costs and improve response times.

## How it works

Every request is assigned a unique cache key. The API first checks if a cached screenshot exists for this key:

1. **Cache found** → Returns cached screenshot immediately (free)
2. **Cache not found** → Captures new screenshot and saves to cache (1 credit)

## Cache key generation

By default, cache keys are generated from:

* HTTP method (`GET`)
* Full URL path with all query parameters

This means identical requests (same URL and parameters) share the same cache.

### Custom cache keys

Override automatic cache key generation with the `cacheKey` parameter:

```bash theme={null}
curl "https://api.domshot.com/shot?key=YOUR_API_KEY&url=https://example.com&cacheKey=my-custom-key"
```

The `cacheKey` is hashed before use, so any string value works.

## Cache duration

Screenshots are cached for **4 hours**.

After expiration, the next request generates a new screenshot and refreshes the cache.

## Cache behavior

| Scenario          | Credits  | Description                             |
| ----------------- | -------- | --------------------------------------- |
| Cache hit         | Free     | Cached screenshot returned              |
| Cache miss        | 1 credit | New screenshot captured and cached      |
| With `fresh=true` | 1 credit | Cache bypassed, new screenshot captured |

## Bypassing cache

Use `fresh=true` to force a new screenshot and ignore cached results:

```bash theme={null}
curl "https://api.domshot.com/shot?key=YOUR_API_KEY&url=https://example.com&fresh=true"
```

This always consumes 1 credit, even if a cached screenshot exists.

## Best practices

* **Leverage cache** - Identical requests within 4 hours are free
* **Use `fresh=true` sparingly** - Only when you need updated content
* **Custom cache keys** - Group related screenshots under shared keys

## See also

* [How Credits Work](/guides/core/credits) - Credit consumption
* [Rate Limits](/guides/core/rate-limits) - Request rate limits