---
title: "One data series' stored values over a range of days"
method: GET
path: "/api/metrics/{metric}/history"
tags: ["Metrics"]
---

# One data series' stored values over a range of days

`GET /api/metrics/{metric}/history`

## Request

- Base URL: `https://api.prereason.com`
- URL: `https://api.prereason.com/api/metrics/{metric}/history`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

The stored values of one financial or economic data series over a range
of days, oldest first, read with a key. Values only: the trend,
percentile and context of the newest reading are at
GET /api/metrics/{metric}.

A value is served only where its own source allows it to be passed on.
Each source is named once in `sources`, with its answer (`display`: yes
or notice) and the notice its terms ask for. `served_from` is the first
date served. A series whose values its sources do not allow to be
passed on is answered 404.

`as_of` serves only what was public by the end of that day (23:59:59
UTC), and gives each value its `known_since` and `known_basis`, as a
dated briefing does. A series its source revises is served as stored,
with `note` saying so.

`interval=week` or `interval=month` gives each period's last stored
reading, never an average. One answer carries at most 5,000 values,
and `next_from` names the `from` that reads on.

History by plan: Basic the last 3 years, Pro and above every stored
date. A key that reads only a metric's latest reading at
GET /api/metrics/{metric} reads none of its history. There is no pay
per call price for this route.

## Path parameters

- `metric` string, required

## Query parameters

- `from` string
- `to` string
- `as_of` string
- `interval` 'day' | 'week' | 'month'

## Response `200`

The series' served values in the range

- object
  - `metric` string
  - `display_name` string
  - `from` string
  - `to` string
  - `as_of` string: On a dated read only.
  - `as_of_cutoff` string: On a dated read only, the instant nothing published after is served.
  - `interval` string
  - `served_from` string: The first date served. Absent when the range has no value.
  - `count` integer
  - `next_from` string: Present when more values remain; pass it as `from` to read on.
  - `display` 'yes' | 'notice': The most restricted answer of the sources served.
  - `sources` object[]
    - `name` string
    - `display` 'yes' | 'notice'
    - `points` integer
    - `first_date` string
    - `last_date` string
    - `notices` string[]: Each notice this source's terms ask for, once.
  - `note` string: On a series its source revises.
  - `data` object[]
    - `date` string
    - `value` number
    - `source` string: The source this value came from.
    - `known_since` string, nullable: On a dated read only, the instant the value was public by.
    - `known_basis` 'released' | 'fetched' | 'release_schedule' | 'unknown': On a dated read only, what dates `known_since`.

## Other responses

- `400`: A date or interval that does not parse, or `from` after `to` or `as_of`
- `401`: Authentication required
- `403`: A range before the first day your plan reads (DATE_RESTRICTED), or a metric your key reads only the latest reading of (TIER_RESTRICTED)
- `404`: Resource not found
- `429`: Rate limit exceeded

## Changes

- **2026-10-31** `ede8fdbdd4e1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/prereason/apis/prereason-api/changes/api/metrics/:metric/history/get.md)

---

[API](https://skmtc.dev/prereason/apis/prereason-api.md) - [All operations](https://skmtc.dev/prereason/apis/prereason-api/llms.txt) - [OpenAPI document](https://skmtc.dev/prereason/apis/prereason-api/revisions/fe5bacbc7887?raw)