---
title: "Historical rate time-series per product/state"
method: POST
path: "/v1/rate-history"
tags: ["Data & Analytics"]
---

# Historical rate time-series per product/state

`POST /v1/rate-history`

## Request

- Base URL: `https://api.rateapi.dev`
- URL: `https://api.rateapi.dev/v1/rate-history`
- Auth: API key in header `X-API-Key`

Returns a date-ranged, point-in-time rate time-series for a product/state over a requested window (bounded by data retention). Each point is a day or week bucket with min/median/max APR and a count of underlying offers; empty buckets are included with count 0 and null values so the series is chart-ready. Also returns a summary of the move across the window (first vs last median, delta, down/up/flat direction). Differs from `/v1/rate-delta` (a single now-vs-then comparison): this returns the full series for dashboards, charts, backtests, and timing confidence. This route is the single source of truth; the MCP `get_rate_history` tool and the consumer app call it.

**Authentication required**: Pass your API key in the `X-API-Key` header.

## Request body

- object
  - `product_type` 'auto_loan' | 'mortgage' | 'heloc' | 'personal_loan' | 'student_loan' | 'credit_card', required: Loan or deposit product this applies to.
  - `state` string, required: 2-letter US state code
  - `window` '30d' | '60d' | '90d' | '180d' | '365d': Lookback window. Defaults to 90d. Bounded by data retention; bad values clamp to the default.
  - `interval` 'day' | 'week': Bucket granularity per point. Defaults to week; bad values clamp to the default.
  - `vehicle_condition` 'new' | 'used' | 'cpo': auto_loan only; selects the benchmark bucket. Defaults to new.

## Response `200`

Ascending time-series of bucketed rate stats plus a summary. Degrades to an empty series with an explanatory note when history is thin.

- object
  - `product_type` string: Loan or deposit product this applies to.
  - `state` string: Two-letter US state code.
  - `window` string: How far back the series reaches.
  - `interval` string: How the series is bucketed.
  - `series` object[]: One point per interval, oldest first.
    - `date` string: Bucket start (YYYY-MM-DD, UTC)
    - `min` number, nullable: Lowest APR in this interval, or null when it held no offers.
    - `median` number, nullable: Median APR in this interval, or null when it held no offers.
    - `max` number, nullable: Highest APR in this interval, or null when it held no offers.
    - `count` integer: How many offers this interval’s figures were computed from.
  - `summary` object, nullable: How the series moved from end to end, or null when there were too few points to compare.
    - `first` object: The earliest point in the series.
    - `last` object: The most recent point in the series.
    - `median_delta_pct` number: Change in median APR between those two points, in percentage points. Negative means rates eased.
    - `direction` 'down' | 'up' | 'flat': Which way the value moved over the window.
    - `points` integer: Discount points priced into the rate.
    - `as_of` string, nullable: When the underlying rates were published.
  - `note` string: Plain-language explanation of what this result means.

## Other responses

- `400`: The request was malformed — a missing required field, an unparseable body, or a parameter outside its allowed range. The `error` field names what was wrong; retrying the identical request will fail identically.
- `401`: No API key, or a key that is unknown or disabled. Send it in the `X-API-Key` header. Free keys are issued instantly by POST /keys with an email address. The response carries `WWW-Authenticate` pointing at this host's protected-resource metadata, and the `RateLimit-*` headers describing the Free-tier budget a key issued now would carry (scope `anonymous`) — a rejected request spends none of it, so `Remaining` equals `Limit`.
- `429`: Quota exhausted for the current window. `Retry-After` gives the seconds to wait; `upgradeInfo` explains how to lift the cap. Retrying before the reset will fail again and still counts as a request.

---

[API](https://skmtc.dev/rateapi/apis/rate-api.md) · [All operations](https://skmtc.dev/rateapi/apis/rate-api/llms.txt) · [OpenAPI document](https://skmtc.dev/rateapi/apis/rate-api/revisions/06a6db76995f?raw)