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

# Freshness + cache patterns

> When to call, when to cache, when to ask for a refresh.

## The freshness signals

Every BETA response that includes intelligence carries timestamps you should pay attention to:

| Field                            | Meaning                                                     |
| -------------------------------- | ----------------------------------------------------------- |
| `meta.enrichedAt`                | When this response was assembled (always "now")             |
| `intelligence.generated_at`      | When the SWOT/competitors/priorities synthesis was last run |
| `_meta.snapshot_at` (in samples) | When the underlying weekly snapshot was generated           |

Material events arrive within 24h of SEC filing. SWOT / competitor / priority synthesis is rerun weekly per entity.

## Recommended cache strategy

For most agent workflows:

```javascript theme={null}
const CACHE_TTL_SECONDS = 7 * 24 * 60 * 60; // 1 week

async function getEnrichmentCached(redis, company) {
  const cacheKey = `beta:enrich:${company.toLowerCase()}`;
  const cached = await redis.get(cacheKey);
  if (cached) return JSON.parse(cached);

  const fresh = await fetch('https://api.getbeta.io/api/v1/enrich', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.BETA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ company, include: ['intelligence'] })
  }).then(r => r.json());

  await redis.setex(cacheKey, CACHE_TTL_SECONDS, JSON.stringify(fresh));
  return fresh;
}
```

## When NOT to cache

* **`/corroborate` calls** — these are claim-specific and shouldn't be cached. Always hit the live API.
* **Pre-trade or compliance decisions** — fetch fresh; don't rely on a 7-day-old snapshot.
* **Workflows that depend on intra-week news shifts** — cache for shorter (e.g., 24h) or skip caching.

## Detecting stale data

```javascript theme={null}
function isStale(response, maxAgeDays = 14) {
  const ts = response.intelligence?.generated_at || response.meta?.enrichedAt;
  if (!ts) return false;
  const ageDays = (Date.now() - new Date(ts).getTime()) / 86_400_000;
  return ageDays > maxAgeDays;
}
```

If a response is stale, BETA's automated weekly refresh missed this entity. Email **[hello@getbeta.io](mailto:hello@getbeta.io)** — a manual refresh is a one-line ticket on our side.

## Force-refresh (coming soon)

Programmatic force-refresh is on the [Roadmap](/roadmap). Today it's internal-only.