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

# Macro Historical Observations

> Latest-vintage historical time series for a single U.S. macro indicator.

<Note icon="sparkles">
  **Available as MCP tools**: `macro_indicator_search` + `macro_indicator_history` — call directly from Claude / Cursor / any MCP client. See [MCP Server](/en/integration/mcp-server) for the 60-second setup.
</Note>

<Badge color="green" icon="circle-check">Live</Badge>
 
<Badge color="blue" size="sm">1 credit · history</Badge>
 
<Badge color="gray" size="sm">free · search</Badge>

## What it does for your agent

`macro_indicator_history` returns the **latest-vintage historical time series** for one supported U.S. macro indicator (CPI, UNRATE, Fed Funds, 10Y yield, GDP, etc.) — a list of `{ date, value, realtime_start, realtime_end }` observations. Use it as a **macro time-series fetcher** mid-task: when an agent needs to chart inflation over the last 5 years, compute a yield-curve slope, or feed observations into a downstream model.

The canonical agent flow is two-step: call `macro_indicator_search` first (free) to locate the right `indicator` alias, then `macro_indicator_history` to pull the series. Two query modes:

* **Recent mode** — pass `limit` (default `60`) for the most recent N observations.
* **Range mode** — pass `start_date + end_date` for an explicit window.

## Agent flow

```mermaid theme={null}
sequenceDiagram
  participant Agent
  participant MCP as data-mcp
  Agent->>MCP: macro_indicator_search(q?, category?, frequency?)
  MCP-->>Agent: items[] · indicator · series_id · frequency · units
  Note over Agent: pick the right alias
  alt question is "what's the trend?"
    Agent->>MCP: macro_indicator_history(indicator, limit=60)
    MCP-->>Agent: observations[] · date · value · realtime_start
  else question is "between two dates"
    Agent->>MCP: macro_indicator_history(indicator, start_date, end_date)
    MCP-->>Agent: observations[] · within window
  end
  Note over Agent: chart, compare, or feed downstream
```

## Response

<ResponseField name="data" type="MacroHistorical" required>
  Indicator metadata + observations array.

  <Expandable title="MacroHistorical fields">
    <ResponseField name="indicator" type="string" required>
      Stable platform alias echoed back (e.g. `us.cpi.headline`).
    </ResponseField>

    <ResponseField name="series_id" type="string" required>
      Raw series ID (e.g. `CPIAUCSL`).
    </ResponseField>

    <ResponseField name="title" type="string" required>
      Human-readable indicator title.
    </ResponseField>

    <ResponseField name="frequency" type="string" required>
      Native cadence: `Daily`, `Weekly`, `Monthly`, `Quarterly`, `Annual`.
    </ResponseField>

    <ResponseField name="units" type="string" required>
      Unit string (e.g. `Index 1982-1984=100`, `Percent`).
    </ResponseField>

    <ResponseField name="observations" type="MacroObservation[]" required>
      Time-ordered observations (oldest → newest).

      <Expandable title="MacroObservation fields">
        <ResponseField name="date" type="string" required>
          Observation period start (YYYY-MM-DD).
        </ResponseField>

        <ResponseField name="value" type="number" nullable>
          Reported value. `null` when the period is missing.
        </ResponseField>

        <ResponseField name="realtime_start" type="string" required>
          First date this value was published (YYYY-MM-DD). Use to detect revisions.
        </ResponseField>

        <ResponseField name="realtime_end" type="string" required>
          Last date this value remained current. Same as `realtime_start` for the latest vintage of an unchanged value.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="attribution" type="string" required>
      Required attribution string for display.
    </ResponseField>

    <ResponseField name="stale" type="boolean" required>
      `true` if the response uses older available data after a refresh failed.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Credits consumed (always `1`).</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Account credits remaining.</ResponseField>

```json title="200 OK · macro_indicator_history" expandable theme={null}
{
  "data": {
    "indicator": "us.cpi.headline",
    "series_id": "CPIAUCSL",
    "title": "Consumer Price Index for All Urban Consumers: All Items in U.S. City Average",
    "frequency": "Monthly",
    "units": "Index 1982-1984=100",
    "observations": [
      {
        "date": "2026-01-01",
        "value": 318.412,
        "realtime_start": "2026-02-12",
        "realtime_end": "2026-02-12"
      },
      {
        "date": "2026-02-01",
        "value": 319.082,
        "realtime_start": "2026-03-12",
        "realtime_end": "2026-03-12"
      },
      {
        "date": "2026-03-01",
        "value": 319.799,
        "realtime_start": "2026-04-10",
        "realtime_end": "2026-04-10"
      }
    ],
    "attribution": "Source: U.S. Bureau of Labor Statistics via FRED",
    "stale": false
  },
  "meta": {
    "creditsUsed": 1,
    "remainingCredits": 99
  }
}
```

<Note>
  Each series carries its own `attribution` string (FRED source notice) under `data` — surface it when you display the data. This product uses the FRED® API but is not endorsed or certified by the Federal Reserve Bank of St. Louis.
</Note>

## Notes

<Tip>
  **Revision-aware**: macro observations get revised. The series returns the **current latest vintage**, not the value released originally. Use `realtime_start` / `realtime_end` to detect whether you're seeing a revised print. As-of vintage replay is not currently supported.
</Tip>

<Tip>
  Default `limit=60` covers \~5 years for monthly series, \~1 year for weekly, \~3 months for daily. Bump to `500` or use Range mode for longer windows. Popular indicators usually return faster on repeated calls.
</Tip>

<Warning>
  **Recent and Range are mutually exclusive.** Pass either `limit` alone, or `start_date + end_date` together. Passing only one of `start_date` / `end_date` returns `400`.
</Warning>

<Warning>
  **Supported catalog only.** \~50 curated U.S. indicators. Arbitrary `series_id` values outside the catalog return `404`. Use `macro_indicator_search` to discover what's available.
</Warning>

## Direct invocation

<Accordion title="HTTP / SDK examples" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // 1) Discover the alias
    {
      "method": "tools/call",
      "params": {
        "name": "macro_indicator_search",
        "arguments": { "q": "cpi", "category": "Inflation" }
      }
    }

    // 2) Fetch recent history (default 60)
    {
      "method": "tools/call",
      "params": {
        "name": "macro_indicator_history",
        "arguments": { "indicator": "us.cpi.headline", "limit": 60 }
      }
    }

    // 2b) Or fetch an explicit date range
    {
      "method": "tools/call",
      "params": {
        "name": "macro_indicator_history",
        "arguments": {
          "indicator": "us.cpi.headline",
          "start_date": "2020-01-01",
          "end_date": "2026-03-01"
        }
      }
    }
    ```

    ```python Python (HTTP) theme={null}
    import os, requests

    base = "https://api.llmquantdata.com"
    headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}

    # 1) Discover the alias
    catalog = requests.get(
        f"{base}/api/macro/indicators",
        headers=headers,
        params={"q": "cpi", "category": "Inflation"},
    ).json()["data"]

    alias = catalog[0]["indicator"]  # e.g. us.cpi.headline

    # 2) Fetch recent history
    hist = requests.get(
        f"{base}/api/macro/historical",
        headers=headers,
        params={"indicator": alias, "limit": 60},
    ).json()
    for obs in hist["data"]["observations"][-3:]:
        print(obs["date"], obs["value"])
    ```

    ```bash cURL theme={null}
    # 1) Discover the alias
    curl "https://api.llmquantdata.com/api/macro/indicators?q=cpi&category=Inflation" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"

    # 2) Fetch recent history (Recent mode)
    curl "https://api.llmquantdata.com/api/macro/historical?indicator=us.cpi.headline&limit=60" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"

    # 2b) Range mode
    curl "https://api.llmquantdata.com/api/macro/historical?indicator=us.cpi.headline&start_date=2020-01-01&end_date=2026-03-01" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## Full parameter reference

<AccordionGroup>
  <Accordion title="macro_indicator_search — request parameters" icon="magnifying-glass">
    <ParamField query="q" type="string">
      Free-text keyword. Matches indicator alias, indicator title, and `series_id`.
    </ParamField>

    <ParamField query="category" type="string">
      Filter by theme (`Inflation`, `Rates`, `Labor`, `Growth`, `Housing`, `Liquidity`, `Conditions`, `FX`, `Credit`, `Sentiment`, `Energy`, `Inflation Expectations`, `Consumption`).
    </ParamField>

    <ParamField query="frequency" type="string">
      Filter by cadence (`Daily`, `Weekly`, `Monthly`, `Quarterly`, `Annual`).
    </ParamField>

    <ParamField query="limit" type="number" default={20}>
      Max items returned. Range `1–100`.
    </ParamField>
  </Accordion>

  <Accordion title="macro_indicator_history — request parameters" icon="chart-line">
    <ParamField query="indicator" type="string">
      Platform alias (e.g. `us.cpi.headline`, `us.rates.fed_funds`). Use this **OR** `series_id`.
    </ParamField>

    <ParamField query="series_id" type="string">
      Raw series ID (e.g. `CPIAUCSL`). Use this **OR** `indicator`. Must be in the supported catalog.
    </ParamField>

    <ParamField query="start_date" type="string">
      Range mode. ISO date `YYYY-MM-DD`. Must be paired with `end_date`.
    </ParamField>

    <ParamField query="end_date" type="string">
      Range mode. ISO date `YYYY-MM-DD`. Must be paired with `start_date`.
    </ParamField>

    <ParamField query="limit" type="number" default={60}>
      Recent mode count. Range `1–500`. Ignored when Range mode is used.
    </ParamField>
  </Accordion>
</AccordionGroup>

## Related

<Columns cols={2}>
  <Card title="Macro Indicators Catalog" icon="landmark" href="/en/api/macro/indicators">
    Discover the \~50-indicator catalog (free).
  </Card>

  <Card title="Macro Snapshot" icon="gauge-high" href="/en/api/macro/snapshot">
    Just the latest print + delta vs previous (no full series).
  </Card>
</Columns>