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

# Freshness and liveness

> Every observation carries a freshness label, gated per frequency. A separate liveness check detects feeds that have silently stopped updating.

A value can be wrong in two ways: it can be old, or its source can have quietly died. Financial Data API addresses both. Every observation carries a **freshness label** computed against a per-frequency gate, and a separate **liveness check** watches every series for sources that have silently stopped updating. The first tells you about a single value. The second tells you about the health of the pipe feeding it.

## The freshness label

Every observation includes a freshness label with one of three values:

<Columns cols={3}>
  <Card title="fresh" icon="circle-check" color="#FAFAFA">
    The value is recent enough for its frequency. The source is delivering on cadence.
  </Card>

  <Card title="stale" icon="clock" color="#A3A3A3">
    The value is older than its frequency gate allows. Usable, but treat with caution.
  </Card>

  <Card title="unknown" icon="circle-question" color="#6B6B6B">
    Freshness could not be determined for this value.
  </Card>
</Columns>

The label travels inline on the observation, so you can branch on it without a second request.

```bash theme={"theme":"css-variables"}
# Latest US inflation, with its freshness label inline
curl -G "https://api.financialdatapi.com/observations/latest" \
  -H "x-api-key: $FINANCIALDATA_API_KEY" \
  --data-urlencode "country=USA" \
  --data-urlencode "indicator=cpi_inflation_yoy"
```

### Filtering by freshness

Most observation routes accept a `freshness` filter, so you can ask for only the values that pass the gate.

<ParamField query="freshness" type="string">
  One of `fresh`, `stale`, or `unknown`. Returns only observations with the matching label.
</ParamField>

<CodeGroup>
  ```bash cURL theme={"theme":"css-variables"}
  curl -G "https://api.financialdatapi.com/observations" \
    -H "x-api-key: $FINANCIALDATA_API_KEY" \
    --data-urlencode "country=USA" \
    --data-urlencode "indicator=cpi_inflation_yoy" \
    --data-urlencode "freshness=fresh"
  ```

  ```python Python theme={"theme":"css-variables"}
  import os, requests

  resp = requests.get(
      "https://api.financialdatapi.com/observations",
      headers={"x-api-key": os.environ["FINANCIALDATA_API_KEY"]},
      params={
          "country": "USA",
          "indicator": "cpi_inflation_yoy",
          "freshness": "fresh",
      },
  )
  resp.raise_for_status()
  print(resp.json()["data"])
  ```

  ```typescript TypeScript theme={"theme":"css-variables"}
  import { FinancialDataApiClient } from "@financialdatapi/client";

  const client = new FinancialDataApiClient({ apiKey: process.env.FINANCIALDATA_API_KEY });

  const { data } = await client.getObservations({
    country: "USA",
    indicator: "cpi_inflation_yoy",
    freshness: "fresh",
  });
  console.log(data);
  ```
</CodeGroup>

<Tip>
  The public screener also accepts `freshness=fresh`, so you can screen countries on values that are confirmed current. See the screener guide for the filter DSL.
</Tip>

## Per-frequency freshness gates

"Recent" means different things for different series. A daily FX reference rate that is a week old is badly stale; a quarterly GDP figure that is a week old is brand new. Financial Data API applies the freshness gate **per frequency**, so each series is judged against a window appropriate to how often it is published.

<Info>
  A daily series and a quarterly series can both be labeled `fresh` while having very different ages, because each is measured against its own gate. The label answers "is this on cadence for its frequency?", not "how many days old is this in absolute terms?"
</Info>

This is why freshness is a label rather than a raw age: the gate encodes the expected cadence so you do not have to maintain a table of acceptable staleness per indicator yourself.

## Liveness: catching silently-frozen feeds

Freshness tells you whether a value is recent. It does not, on its own, tell you whether a source has *stopped*. A feed that froze last month can keep returning the same last-known value, and each individual observation might still look defensible. Liveness exists to catch exactly that failure mode.

Financial Data API runs a per-series liveness check that detects feeds which have silently stopped updating, across the connector fleet. You can read its results:

```
GET /ops/liveness
```

<Note>
  The operational routes require the `ops:read` scope. A key scoped only for `data:read` will receive `403 forbidden`. Request `ops:read` if you need to monitor feed health programmatically.
</Note>

<CodeGroup>
  ```bash cURL theme={"theme":"css-variables"}
  curl -G "https://api.financialdatapi.com/ops/liveness" \
    -H "x-api-key: $FINANCIALDATA_API_KEY"
  ```

  ```python Python theme={"theme":"css-variables"}
  import os, requests

  resp = requests.get(
      "https://api.financialdatapi.com/ops/liveness",
      headers={"x-api-key": os.environ["FINANCIALDATA_API_KEY"]},
  )
  resp.raise_for_status()
  print(resp.json()["data"])
  ```

  ```typescript TypeScript theme={"theme":"css-variables"}
  import { FinancialDataApiClient } from "@financialdatapi/client";

  const client = new FinancialDataApiClient({ apiKey: process.env.FINANCIALDATA_API_KEY });

  const { data } = await client.request("/ops/liveness");
  console.log(data);
  ```
</CodeGroup>

<Warning>
  Freshness and liveness answer different questions and you should monitor both. A value can be labeled `stale` simply because nothing new was due yet, and a value can look `fresh` while the source behind it has frozen. Use the freshness label per observation and the liveness check per series.
</Warning>

## Choosing the right signal

<AccordionGroup>
  <Accordion title="I am consuming a single value for a decision" icon="circle-check">
    Read the inline `freshness` label, or pass `freshness=fresh` to exclude anything past its gate. This is the per-value check.
  </Accordion>

  <Accordion title="I am building a dashboard or strategy on many series" icon="signal">
    Poll `GET /ops/liveness` to catch sources that have silently frozen before they quietly corrupt your inputs. This is the per-series, fleet-wide check.
  </Accordion>

  <Accordion title="I want a higher-level view of source health" icon="heart-pulse">
    `GET /source-health` reports source and connector freshness at the source level, complementing the per-series liveness check.
  </Accordion>
</AccordionGroup>

<Check>
  Use the freshness label to judge a value and the liveness check to judge the pipe. Together they keep stale numbers and dead feeds out of your decisions.
</Check>

## Related

<Columns cols={2}>
  <Card title="The time model" icon="clock" href="/concepts/time-model">
    How knowledge time and vintage relate to when a value became known.
  </Card>

  <Card title="Provenance" icon="link" href="/concepts/provenance">
    Trace any observation back to its source and ingestion run.
  </Card>
</Columns>