API Reference

Programmatic access to all data. Free API key, 300 requests/minute.

Getting started

Base URL: https://api.hfdatalibrary.com/v1

Data requests require an API key passed as a header. /symbols and /symbols/{ticker} are public and need no key:

curl -H "X-API-Key: your-key-here" \
  https://api.hfdatalibrary.com/v1/bars/AAPL?version=clean

API keys are free and expire every 30 days. Register here with your name, institution, and email.

Rate limit: 100 data downloads per minute per account, 300 general requests per minute. Responses include X-RateLimit-Remaining and X-RateLimit-Reset headers.

What the data endpoints return: a whole-ticker Parquet file, streamed from storage — not JSON rows. There is no server-side date filtering: you download a ticker's full history once and slice it locally (pandas, polars, DuckDB, arrow). For a different bar interval or CSV instead of Parquet, use the signed-URL flow at the bottom of this page.

Endpoints

GET /symbols

List every available ticker with its file size and last-updated time. No API key needed — this endpoint is public.

GET /v1/symbols

{
  "count": 1391,
  "symbols": [
    {
      "ticker": "A",
      "size_bytes": 37333824,
      "last_modified": "2026-08-08T11:05:56.651Z"
    },
    ...
  ]
}
GET /symbols/{ticker}

File size and last-updated time for one ticker, per version. No API key needed.

GET /v1/symbols/AAPL

{
  "ticker": "AAPL",
  "versions": {
    "raw":   { "size_bytes": 44735570, "last_modified": "2026-08-08T11:07:01.907Z" },
    "clean": { "size_bytes": 43755784, "last_modified": "2026-08-08T11:07:02.257Z" }
  }
}
GET /bars/{ticker}

The ticker's complete 1-minute OHLCV history as a single Parquet file. Requires X-API-Key, a verified email, and a complete profile. Typical size is 30–60 MB per ticker.

Parameters

ParamTypeDefaultDescription
versionstringcleanraw or clean — the only parameter this endpoint takes
 
curl -H "X-API-Key: YOUR_KEY" -o AAPL_clean.parquet \
  "https://api.hfdatalibrary.com/v1/bars/AAPL?version=clean"

# 200 OK · Content-Type: application/octet-stream
# Content-Disposition: attachment; filename="AAPL_clean.parquet"

# then, locally:
import pandas as pd
df = pd.read_parquet("AAPL_clean.parquet")
day = df.loc["2024-01-02"]        # slice the range you need
GET /variables/{ticker}

All 25 computed academic variables at daily frequency, as a Parquet file covering the ticker's whole history. Requires X-API-Key. Select the columns and dates you want after loading.

Parameters

ParamTypeDefaultDescription
versionstringcleanraw or clean — the only parameter this endpoint takes
 
curl -H "X-API-Key: YOUR_KEY" -o AAPL_variables.parquet \
  "https://api.hfdatalibrary.com/v1/variables/AAPL?version=clean"
GET /quality/{ticker}

Daily data-quality report — gap rate, observed bars, longest gap, bars since last trade — as a Parquet file. Requires X-API-Key; takes the same single version parameter.

GET /download-token/{ticker}  then  /download/{ticker}?token=…

The two-step flow for any bar interval other than 1-minute, and for CSV instead of Parquet. Step 1 authenticates with your X-API-Key and returns a signed URL; step 2 fetches that URL (no header needed) within 10 minutes.

Parameters (step 1)

ParamTypeDefaultDescription
timeframestring1min1min, 5min, 15min, 30min, hourly, daily, weekly, monthly
formatstringparquetparquet or csv
versionstringcleanraw or clean
 
# step 1 — ask for a signed URL (daily bars, CSV)
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.hfdatalibrary.com/v1/download-token/AAPL?timeframe=daily&format=csv&version=clean"

{
  "url": "https://api.hfdatalibrary.com/v1/download/AAPL?token=…",
  "expires_at": "2026-08-08T22:10:00.000Z",
  "version": "clean",
  "timeframe": "daily",
  "format": "csv"
}

# step 2 — fetch it (valid for 10 minutes, no header needed)
curl -o AAPL_daily.csv "PASTE_THE_URL_HERE"

Error codes

CodeMeaning
400Bad request — an unsupported version, format, or timeframe value
401Unauthorized — missing or invalid API key
403Forbidden — email not verified, or profile incomplete (institution, country, role)
404Not found — no such ticker in that version, or no such endpoint
429Rate limit exceeded — wait and retry (see Retry-After header)
500Server error — please report to [email protected]

Every response this API returns — success or error — carries Content-Type: application/json (or application/octet-stream for a data file) and a body. If you receive a status with an empty body and no content type, the response did not come from us: check for a proxy, VPN, or TLS-inspecting appliance between you and the API. A genuine response from our edge always includes a cf-ray header.