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

# Freshness & Staleness

> Understanding content freshness in Ground

# 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.

```json theme={null}
{
  "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

```mermaid theme={null}
flowchart TD
  Sync[Source Synced] --> Fresh[Fresh]
  Fresh --> |Days pass| Check{Days > Budget?}
  Check --> |No| Fresh
  Check --> |Yes| Stale[Stale]
  Stale --> |Re-sync| Fresh
```

## Configuring Staleness

### Via Trust Policy

```bash theme={null}
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:

```bash theme={null}
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

```json theme={null}
{
  "content": "...",
  "freshness_days": 45.2,
  "is_stale": true
}
```

### Staleness Summary

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

### Warnings

```json theme={null}
{
  "warnings": [
    "Results include sources stale beyond 30 day policy: Old API Docs"
  ]
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Set up automated syncs">
    Use cron jobs or CI/CD to trigger syncs regularly and keep content fresh.
  </Accordion>

  <Accordion title="Choose appropriate staleness budgets">
    * API specs: shorter budget (7-14 days)
    * Code repos: medium budget (14-30 days)
    * Stable docs: longer budget (30-90 days)
  </Accordion>

  <Accordion title="Monitor staleness warnings">
    If you frequently see staleness warnings, increase sync frequency for those sources.
  </Accordion>
</AccordionGroup>