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

# Factor freshness

> Interpret daily, intraday, exposure, and portfolio factor recency from returned metadata

Response speed is not factor freshness. Daily and intraday outputs use different clocks and input sets, while portfolio results also depend on what the caller supplied. Evaluate the evidence attached to the specific result.

## Match the clock to the surface

| Surface                        | Evaluate against                                              |
| ------------------------------ | ------------------------------------------------------------- |
| Catalog                        | catalog version and release metadata                          |
| Daily returns                  | last complete U.S. market session and daily materialization   |
| History                        | row-level range, start/end dates, and observation count       |
| Intraday returns               | snapshot timestamp and current market-data inputs             |
| Exposures                      | exposure-model session and source-return session              |
| Portfolio attribution or hedge | holdings, exposures, returns, bars, mappings, and constraints |

Weekends and U.S. market holidays do not create missing daily rows. Early closes or delayed jobs should appear as returned stale or degraded evidence, not be rewritten as current data.

## Ask for the evidence envelope

```bash theme={null}
curl -H "x-api-key: $SECAPI_API_KEY" \
  -H "secapi-version: 2026-03-19" \
  "https://api.secapi.ai/v1/factors/history/VALUE?range=1y&response_mode=compact&include=trust"
```

When included, inspect `freshness.status`, `freshness.asOf`, `freshness.sourcePublishedAt`, `freshness.lagMs`, `materialization.materializationVersion`, and `degradedState`. Availability differs by route and response mode; do not assume every field is present or has the same semantics.

## Decision rules

| Outcome                                 | Appropriate treatment                                                     |
| --------------------------------------- | ------------------------------------------------------------------------- |
| Fresh and materially complete           | retain the evidence with the workflow result                              |
| Fresh but shorter history than required | do not make a long-history or maximum-coverage claim                      |
| Stale daily result                      | wait for current materialization before making a current-data claim       |
| Stale intraday result                   | avoid live-market language; use a completed daily surface when suitable   |
| Degraded portfolio result               | show partial attribution or no-solution context with missing capabilities |

For a historical claim, rely on returned row-level proof rather than the requested range name. Continue with [Factor provenance](/factor-provenance) and [Factor model methodology](/factor-model-methodology).