Freshness + cache patterns - BETA

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:

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

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 — a manual refresh is a one-line ticket on our side.

Force-refresh (coming soon)

Programmatic force-refresh is on the Roadmap. Today it’s internal-only.