> ## 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. Time boundaries are optional: use `start_date` and/or `end_date` to filter the candidate window, then `limit` and `take_from` choose which edge to keep. Results always return oldest first.

## Agent flow

```mermaid theme={null}
sequenceDiagram
  participant Agent
  participant MCP as data-mcp
  Agent->>MCP: macro_indicator_search(query?, 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 "beginning of a window"
    Agent->>MCP: macro_indicator_history(indicator, start_date, end_date, limit=12, take_from=earliest)
    MCP-->>Agent: observations[] · earliest 12 in 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>
<ResponseField name="meta.notice" type="string">Present only when the candidate window held more bars than were returned — i.e. `limit` truncated the result. The message tells the agent to narrow the window or split the query: `More data exists in the requested window than the items returned; narrow the window or split the query to see more.`</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 the latest \~5 years for monthly series, \~1 year for weekly, or \~3 months for daily. Use `start_date` / `end_date` to bound the window, and `take_from=earliest` when you need the first N observations from that window.
</Tip>

<Warning>
  `take_from=earliest` requires `start_date`. If both date boundaries are provided, `start_date` must not be after `end_date`.
</Warning>

<Warning>
  **Supported catalog only.** \~50 curated U.S. indicators. Arbitrary `series_id` values outside the catalog return `400 invalid_request`. 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": { "query": "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 the earliest 12 observations inside 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",
          "limit": 12,
          "take_from": "earliest"
        }
      }
    }
    ```

    ```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={"query": "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?query=cpi&category=Inflation" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"

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

    # 2b) Earliest 12 observations in a bounded window
    curl "https://api.llmquantdata.com/api/macro/historical?indicator=us.cpi.headline&start_date=2020-01-01&end_date=2026-03-01&limit=12&take_from=earliest" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## Full parameter reference

<AccordionGroup>
  <Accordion title="macro_indicator_search — request parameters" icon="magnifying-glass">
    <ParamField query="query" 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">
      Optional inclusive lower boundary, ISO date `YYYY-MM-DD`.
    </ParamField>

    <ParamField query="end_date" type="string">
      Optional inclusive upper boundary, ISO date `YYYY-MM-DD`.
    </ParamField>

    <ParamField query="limit" type="number" default={60}>
      Maximum observations to return after boundary filtering. Range `1–500`.
    </ParamField>

    <ParamField query="take_from" type="string" default="latest">
      Which side of the filtered window to keep when more than `limit` observations match. Use `latest` or `earliest`; output remains chronological.
    </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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.