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

# Interest rates

> Policy rates, money-market benchmarks, 10-year government bond yields, and the 10Y-3M curve spread, per country, as point-in-time observations.

The `rates` family is Financial Data API's interest-rate factor set: the short end (policy and money-market rates), the long end (10-year government bond yields), and a curve measure (the 10Y-3M spread), each with a stable canonical indicator ID that means the same thing in every country. Query the UK policy rate, the US 10-year yield, and a country's curve spread with the same slugs and filters, and join across countries cleanly.

This page leads with the rate series that are available and their units, then shows how to read them through the two observation endpoints.

## What data is available

The `rates` family spans the covered countries, built from a small set of canonical rate shapes, one per country where it exists:

<CardGroup cols={2}>
  <Card title="Policy Rate" icon="building-columns">
    The central bank's headline policy rate. Unit: `percent`.
  </Card>

  <Card title="3-Month Money-Market Benchmark Rate" icon="clock">
    The short-end money-market benchmark. Unit: `percent`.
  </Card>

  <Card title="10-Year Government Bond Yield" icon="chart-line">
    The 10-year sovereign benchmark yield. Unit: `percent`.
  </Card>

  <Card title="10Y-3M Yield-Curve Spread" icon="arrows-left-right">
    The slope of the curve: 10-year yield minus the 3-month rate. Unit: `percentage_points`.
  </Card>
</CardGroup>

These shapes span the covered countries (plus 2/5/30-year yields where published); the exact per-country availability is live, so treat this as a map and read the authoritative, machine-readable list from `GET /canonical-indicators` and the breadth summary from `GET /coverage`.

### Units

Rate series carry an explicit `unit`. Two units appear in this family, and branching on `unit` matters because levels and spreads are not the same thing:

<Columns cols={2}>
  <Card title="percent" icon="percent">
    Rate levels: Policy Rate, 3-Month Money-Market Benchmark Rate, 10-Year Government Bond Yield. A value of `4.5` means 4.5 percent.
  </Card>

  <Card title="percentage_points" icon="plus-minus">
    Differences between two rates: the 10Y-3M Yield-Curve Spread. A value of `-0.4` means the 10-year yield is 0.4 percentage points below the 3-month rate (an inverted curve).
  </Card>
</Columns>

<Tip>
  A `percent` value is a level you can read directly. A `percentage_points` value is a gap: it can be negative when the curve is inverted (short rates above long rates). Do not treat the two units as interchangeable.
</Tip>

### Country coverage

Rate series are keyed by ISO 3166-1 alpha-3 country code, drawn from the same covered macro universe:

```text theme={"theme":"css-variables"}
ARE AUS CAN CHE DEU EUR GBR HKG JPN KOR
NOR NZL QAT SAU SGP SWE USA
```

Coverage is not uniform: not every country carries all four rate series, so the family totals fewer series than four times the country count. Confirm exactly which rate series a country carries with `GET /coverage` and resolve the live indicator universe with `GET /canonical-indicators`.

<Note>
  These are rate and yield series sourced from institutions of record. Financial Data API publishes official daily [FX reference rates](/apis/fx) separately, but it does not sell raw vendor or real-time market price-tick data: that is redistribution-blocked and deliberately not part of the product.
</Note>

## Canonical indicator IDs

Each rate series has a canonical indicator ID, a stable slug identical across countries, returned on every observation as `indicatorId`. You query by it and join on it. The complete, current list of rate indicator IDs (with names, families, and units) is served live:

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

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

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

  const indicators = await client.listIndicators();
  const rates = indicators.data.filter((ind) => ind.category === "rates");
  for (const ind of rates) {
    console.log(ind.indicatorId, ind.indicatorName, ind.unit);
  }
  ```
</CodeGroup>

<Tip>
  Use `GET /canonical-indicators` to confirm the exact rate slug for the country you want before building queries. Financial Data API fails closed on unknown query parameters and rejects unrecognized indicators with `bad_request`.
</Tip>

## Querying the data

Rate values are served as observations, the same as every other macro factor. An observation is a single value a series describes for a single period, for example the US 10-year government bond yield on a given day. Two public endpoints cover the two shapes you need: a time series, and the latest value per indicator.

<CardGroup cols={2}>
  <Card title="GET /observations" icon="list">
    The history. Time series of public rate observations across periods and vintages. Cursor-paginated.
  </Card>

  <Card title="GET /observations/latest" icon="bolt">
    The snapshot. The single latest public reading per rate indicator. The fastest way to ask "where are rates now."
  </Card>
</CardGroup>

Both endpoints go to `https://api.financialdatapi.com`, require a key with the `data:read` scope, and send the key in the `x-api-key` header (or `Authorization: Bearer`). They share one filter set and one response shape.

### Authentication

```bash theme={"theme":"css-variables"}
-H "x-api-key: $FINANCIALDATA_API_KEY"
```

A `data:read` scope is required. See [Authentication](/authentication).

### Filters

Both endpoints accept the same filters. Combine them freely; they are AND-ed. Unknown query parameters are rejected with `bad_request` (Financial Data API fails closed).

<ParamField query="country" type="string">
  ISO 3166-1 alpha-3 country code, for example `USA`, `GBR`, `DEU`. One of the covered countries.
</ParamField>

<ParamField query="indicator" type="string">
  Canonical rate indicator slug. Also accepted as `indicator_id`. Omit it to pull a country's full set of latest readings in one query, then keep the rate series by matching each row's `indicatorId` against the rate indicator IDs from `/canonical-indicators` (where `category` is `rates`).
</ParamField>

<ParamField query="frequency" type="string">
  Publication cadence: `daily`, `weekly`, `monthly`, `quarterly`, or `annual`.
</ParamField>

<ParamField query="freshness" type="string">
  Keep only readings with a given freshness label: `fresh`, `stale`, or `unknown`. The label is set by a per-frequency age gate, independent of any source self-report.
</ParamField>

<ParamField query="source_id" type="string">
  Financial Data API source id. Filter to a single institution of record.
</ParamField>

<ParamField query="provider_id" type="string">
  Financial Data API provider id or name. Also accepted as `provider`.
</ParamField>

Time filters run on two axes (period: what a value describes; knowledge-time: when it became known):

<ParamField query="period" type="string">
  Convenience filter on the described period: `YYYY`, `YYYY-MM`, or `YYYY-Qn`.
</ParamField>

<ParamField query="period_end" type="string">
  Upper bound on the described period (`YYYY-MM-DD`).
</ParamField>

<ParamField query="start_date" type="string">
  Lower bound on knowledge-time (`observed_at`).
</ParamField>

<ParamField query="end_date" type="string">
  Upper bound on knowledge-time (`observed_at`).
</ParamField>

<ParamField query="as_of" type="string">
  Returns the latest vintage known on or before a timestamp. See the caveat below.
</ParamField>

<ParamField query="limit" type="integer">
  Page size, 1 to 500. Defaults to 100. Follow `meta.pagination.next_cursor` with `cursor` while `has_more` is true. `sort` and `order` (`asc`, `desc`) control ordering.
</ParamField>

<Warning>
  `as_of` currently approximates the ingestion timestamp, not full provider-vintage reconstruction. Revisions are retained and never overwritten, so the revision history is visible, but reconstructing the exact value a provider had published at an arbitrary past instant is future work. Read `as_of` as "what Financial Data API knew by this time."
</Warning>

### Response fields

Public observations come back in camelCase. The fields most relevant to rate series:

<ResponseField name="observationId" type="string">
  Stable ID for this observation. Pass it to `GET /provenance/observations/{observationId}` for the full source chain.
</ResponseField>

<ResponseField name="indicatorId" type="string">
  Canonical rate indicator slug. Use it to query and join across countries.
</ResponseField>

<ResponseField name="indicatorName" type="string">
  Human-readable indicator name, for example `10-Year Government Bond Yield`.
</ResponseField>

<ResponseField name="country" type="string">
  ISO 3166-1 alpha-3 country code.
</ResponseField>

<ResponseField name="actual" type="number">
  The headline numeric value. A rate level (in `percent`) or a spread (in `percentage_points`), per `unit`.
</ResponseField>

<ResponseField name="unit" type="string">
  `percent` for rate levels, `percentage_points` for the curve spread.
</ResponseField>

<ResponseField name="period" type="string">
  Label for the period the value describes, for example `2026-06-10`.
</ResponseField>

<ResponseField name="periodEnd" type="string">
  End of the described period (`YYYY-MM-DD`).
</ResponseField>

<ResponseField name="frequency" type="string">
  Publication cadence.
</ResponseField>

<ResponseField name="observedAt" type="string">
  Knowledge-time: the point at which the value is observed.
</ResponseField>

<ResponseField name="freshnessStatus" type="string">
  Freshness label: `fresh`, `stale`, or `unknown`.
</ResponseField>

<ResponseField name="provider" type="string">
  The provider name behind the source, for example `Bank of England`.
</ResponseField>

<ResponseField name="sourceUrl" type="string">
  The official source URL for the series.
</ResponseField>

<ResponseField name="rawAvailable" type="boolean">
  Whether a raw payload reference is exposed for this observation through the provenance endpoint.
</ResponseField>

## Examples

### A country's full rates set (latest)

Pull every rate series Financial Data API holds for one country in a single latest call, then keep the `rates` family. Because `/observations/latest` returns the latest reading per canonical indicator, one country query gives you the policy rate, the money-market benchmark, the 10-year yield, and the curve spread together.

<CodeGroup>
  ```bash cURL theme={"theme":"css-variables"}
  curl -s "https://api.financialdatapi.com/observations/latest?country=USA" \
    -H "x-api-key: $FINANCIALDATA_API_KEY"
  ```

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

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

  // Discover the rate indicator IDs once, then keep only those from the latest readings.
  const catalog = await client.listIndicators();
  const rateIds = new Set(catalog.data.filter((ind) => ind.category === "rates").map((ind) => ind.indicatorId));

  const { data } = await client.getLatestObservations({ country: "USA" });
  const rates = data.filter((obs) => rateIds.has(obs.indicatorId));
  for (const obs of rates) {
    console.log(obs.indicatorName, obs.actual, obs.unit);
  }
  ```
</CodeGroup>

A latest rates response looks like this:

```json theme={"theme":"css-variables"}
{
  "data": [
    {
      "observationId": "obs_us_policy_rate_2026_06_10",
      "indicatorId": "policy_rate",
      "indicatorName": "Policy Rate",
      "country": "USA",
      "actual": 4.5,
      "unit": "percent",
      "period": "2026-06-10",
      "periodEnd": "2026-06-10",
      "frequency": "daily",
      "observedAt": "2026-06-10T00:00:00Z",
      "freshnessStatus": "fresh",
      "provider": "Federal Reserve (via FRED)",
      "sourceUrl": "https://fred.stlouisfed.org/",
      "rawAvailable": false
    },
    {
      "observationId": "obs_us_govt_bond_yield_10y_2026_06_10",
      "indicatorId": "govt_bond_yield_10y",
      "indicatorName": "10-Year Government Bond Yield",
      "country": "USA",
      "actual": 4.1,
      "unit": "percent",
      "period": "2026-06-10",
      "periodEnd": "2026-06-10",
      "frequency": "daily",
      "observedAt": "2026-06-10T00:00:00Z",
      "freshnessStatus": "fresh",
      "provider": "Federal Reserve (via FRED)",
      "sourceUrl": "https://fred.stlouisfed.org/",
      "rawAvailable": false
    }
  ],
  "meta": {
    "request_id": "a1b2...",
    "requestId": "a1b2...",
    "api_version": "v1",
    "pagination": { "limit": 100, "cursor": null, "next_cursor": null, "has_more": false }
  },
  "requestId": "a1b2..."
}
```

<Note>
  The `indicatorId` values above (`policy_rate`, `govt_bond_yield_10y`) illustrate the shape of a rate slug. Confirm the exact IDs from `GET /canonical-indicators` for the country you query.
</Note>

### 10-year yield history

Pull the time series of a country's 10-year government bond yield, oldest first.

<CodeGroup>
  ```bash cURL theme={"theme":"css-variables"}
  curl -s "https://api.financialdatapi.com/observations?country=USA&indicator=govt_bond_yield_10y&period=2025&order=asc&limit=500" \
    -H "x-api-key: $FINANCIALDATA_API_KEY"
  ```

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

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

  for await (const obs of client.paginate("/observations", {
    country: "USA",
    indicator: "govt_bond_yield_10y",
    order: "asc",
  })) {
    console.log(obs.periodEnd, obs.actual);
  }
  ```
</CodeGroup>

### The curve-spread series

The 10Y-3M Yield-Curve Spread is a first-class series in `percentage_points`: read it directly rather than computing it. A negative value means an inverted curve (short rates above long rates).

<CodeGroup>
  ```bash cURL theme={"theme":"css-variables"}
  curl -s "https://api.financialdatapi.com/observations/latest?country=USA&indicator=yield_curve_spread_10y_3m" \
    -H "x-api-key: $FINANCIALDATA_API_KEY"
  ```

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

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

  const { data } = await client.getLatestObservations({
    country: "USA",
    indicator: "yield_curve_spread_10y_3m",
  });

  const spread = data[0];
  console.log(
    spread.actual,
    spread.unit,
    spread.actual < 0 ? "inverted" : "upward sloping",
  );
  ```
</CodeGroup>

<Info>
  Financial Data API also serves stored rates analytics (curve spreads and more) as derived indicators, where each derived value records its input observation IDs and source refs. See [Derived analytics](/apis/derived-analytics).
</Info>

## Provenance

Every rate value traces back to an official release. Pass an `observationId` to the provenance endpoint for the named source, source URL, raw payload reference metadata, and the ingestion run.

```bash theme={"theme":"css-variables"}
curl -s "https://api.financialdatapi.com/provenance/observations/obs_us_policy_rate_2026_06_10" \
  -H "x-api-key: $FINANCIALDATA_API_KEY"
```

Rate series draw on institutions of record, including FRED, ECB, BIS, Bank of England, and Bank of Japan, across roughly 87 source connectors (53 providers).

## Errors

Non-2xx responses share the standard envelope with a stable, machine-readable `code`.

| Code             | Status | Meaning                                                                    |
| ---------------- | ------ | -------------------------------------------------------------------------- |
| `bad_request`    | 400    | Malformed query, an unknown query parameter, or an unrecognized indicator. |
| `unauthorized`   | 401    | Missing or invalid API key.                                                |
| `forbidden`      | 403    | Key lacks the `data:read` scope.                                           |
| `not_found`      | 404    | Resource does not exist.                                                   |
| `rate_limited`   | 429    | Rate limit exceeded; see `details`.                                        |
| `internal_error` | 500    | Unexpected server error.                                                   |

## Related

<Columns cols={2}>
  <Card title="Macro indicators" icon="chart-mixed" href="/apis/macro-indicators">
    Inflation, labor, growth, housing, external, income, and consumption factors.
  </Card>

  <Card title="Derived analytics" icon="function" href="/apis/derived-analytics">
    Stored rates analytics, curve spreads, and other derived indicators with input provenance.
  </Card>

  <Card title="Economic calendar & events" icon="calendar" href="/apis/economic-calendar">
    Central-bank actions and scheduled rate decisions as official events.
  </Card>
</Columns>