# Caching with max_age

Agents often ask the same question twice in one session. `max_age` lets a call reuse a recent response instead of calling the provider again, which is faster and, for paid providers, cheaper.

## How it works

Add `max_age` in seconds to any call:

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"gsc","tool":"gsc_top_queries","input":{"siteUrl":"sc-domain:example.com"},"max_age":3600}'
```

- If a successful response for the **same connection, endpoint or tool, and input** is at most `max_age` seconds old, it is returned with `"cached": true`. The provider is not called and the call costs nothing.
- Otherwise the provider is called as usual, and the fresh response is stored for later calls that pass `max_age`.
- Without `max_age`, the call always goes to the provider and nothing is stored.

`max_age` accepts 0 to 604800 (7 days). `"max_age": 0` always fetches fresh data and stores it, which is useful to warm the cache before a batch of calls. Only successful responses are cached, and cached responses are kept for at most 7 days.

## Choosing a value

| Data | Suggested max_age |
| --- | --- |
| Search Console performance (final after about 3 days) | `86400` (1 day) |
| GA4 reports for past dates | `3600` to `86400` |
| GA4 realtime reports | leave it out |
| Property and site lists | `86400` |
| URL Inspection after you've changed a page | leave it out |

Matching uses the validated input, with defaults filled in: `{"days": 28}` and `{"days": 30}` are different entries, while leaving `days` out matches `{"days": 28}` because 28 is the default. Key order doesn't matter.

## In the logs

Cached calls are logged like any other, with `cached: true`, so you can see how often your agents reuse data.