Skip to main content

​
Freshness & Staleness

Ground tracks how recent your indexed content is, helping you trust search results.

​
Key Concepts

​
Freshness

Freshness is measured as the number of days since a source was last successfully synced. 
{
  "content": "...",
  "freshness_days": 5.2,
  "is_stale": false
}

​
Staleness Budget

The staleness budget is a configurable threshold (default: 30 days) that determines when content is considered stale.

​
Staleness Warning

When a source exceeds its staleness budget:
  • Results from that source are marked is_stale: true
  • A warning is included in the response
  • Results may be filtered depending on policy settings

​
How It Works

​
Configuring Staleness

​
Via Trust Policy

curl -X PUT https://api.trygroundai.com/policy \
  -H "Authorization: Bearer gnd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "staleness_budget_seconds": 604800
  }'
Common staleness budgets:
  • 7 days (604800 seconds) - for rapidly changing content
  • 30 days (2592000 seconds) - default, good for most cases
  • 90 days (7776000 seconds) - for stable documentation

​
Enforcement

Toggle staleness enforcement: 
curl -X PUT https://api.trygroundai.com/policy \
  -H "Authorization: Bearer gnd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "enforce_staleness": true
  }'
When enforce_staleness is true and include_stale is false in the search request, stale results are filtered out entirely.

​
Search Response Signals

​
Per-Result Freshness

{
  "content": "...",
  "freshness_days": 45.2,
  "is_stale": true
}

​
Staleness Summary

{
  "staleness_summary": {
    "total_sources": 5,
    "fresh_sources": 4,
    "stale_sources": 1,
    "staleness_budget_days": 30,
    "stale_source_names": ["Old API Docs"]
  }
}

​
Warnings

{
  "warnings": [
    "Results include sources stale beyond 30 day policy: Old API Docs"
  ]
}

​
Best Practices

Use cron jobs or CI/CD to trigger syncs regularly and keep content fresh.
  • API specs: shorter budget (7-14 days)
  • Code repos: medium budget (14-30 days)
  • Stable docs: longer budget (30-90 days)
If you frequently see staleness warnings, increase sync frequency for those sources.