API Documentation

Everything you need to use Hindsight Data API.

Authentication

All API requests (except /getSample) require authentication using your API key. You can pass your API key in any one of three ways:

1. X-API-Key Header (Recommended)

X-API-Key: hindsight_live_xxxxx

2. Authorization Header (Bearer Token)

Authorization: Bearer hindsight_live_xxxxx

3. Query Parameter

?api_key=hindsight_live_xxxxx

You receive your API key after purchase. You can rotate your key at any time via the API.

Base URL

All API requests should be made to:

https://hindsightapi.com/api

Data Coverage and Status

In addition to historical data, Hindsight Data includes economic prints scheduled for the next 30 days. The dataset is updated once per day.

past_or_future is not a live release status. It is a date-and-time classification refreshed during the daily dataset update. An event may remain marked future until the next refresh after its scheduled time passes.

A populated actual field means a released value was captured. A null value does not always mean an event is unreleased because some events do not publish a numeric actual value. The dataset does not currently include a separate universal scheduled/released field.

Endpoints

GET/getData

Retrieve economic calendar data for a date range. Requires authentication.

Query Parameters

Parameter	Type	Description
`start_date`	string	Start date (YYYY-MM-DD)
`end_date`	string	End date (YYYY-MM-DD)
`country`	string	Filter by country code (US, GB, EU, etc.)
`min_volatility`	integer	Minimum volatility level (1-3, where 3 is highest impact)
`event`	string	Filter by event name (e.g. CFTC, PPI, FOMC)
`format`	string	Response format: `json` (default) or `csv`

Example Requests

JSON format (default):

curl -X GET "https://hindsightapi.com/api/getData?start_date=2024-08-05&end_date=2024-08-05&country=US&event=PMI" \
  -H "X-API-Key: hindsight_live_xxxxx"

CSV format:

curl -X GET "https://hindsightapi.com/api/getData?start_date=2024-08-05&end_date=2024-08-05&format=csv" \
  -H "X-API-Key: hindsight_live_xxxxx"

GET/getSample

Get free sample data (August-September 2023, US markets, volatility 2+). No authentication required.

Example Request

curl "https://hindsightapi.com/api/getSample"

Response Format

Responses can be in JSON or CSV format based on the format query parameter.

JSON Format (Default)

[
  {
    "actual": "3.3%",
    "country": "US",
    "date": "2025-01-13",
    "event_name": "PPI (YoY) (Dec)",
    "forecast": "3.5%",
    "past_or_future": "past",
    "previous": "3.0%",
    "time": "08:30",
    "timezone": "America/New_York",
    "volatility": 2,
    "event_id": "bb1bc3f25ab5a5fb"
  },
  {
    "actual": "0.1%",
    "country": "US",
    "date": "2025-01-13",
    "event_name": "PPI ex. Food/Energy/Transport (MoM) (Dec)",
    "forecast": "0.3%",
    "past_or_future": "future",
    "previous": "0.1%",
    "time": "08:30",
    "timezone": "America/New_York",
    "volatility": 2,
    "event_id": "2cfe8dcaf5c1b9ef"
  }
]

CSV Format

Add format=csv to download data as CSV.

date,past_or_future,time,event_name,actual,forecast,previous,volatility,timezone,country,event_id
2025-01-13,past,06:00,NFIB Small Business Optimism  (Dec),105.1,101.3,101.7,2,America/New_York,US,47ee42baa88a9b03
2025-01-13,past,08:30,PPI (YoY) (Dec),3.3%,3.5%,3.0%,2,America/New_York,US,bb1bc3f25ab5a5fb
2025-01-13,future,08:30,PPI ex. Food/Energy/Transport (MoM) (Dec),0.1%,0.3%,0.1%,2,America/New_York,US,2cfe8dcaf5c1b9ef

Field Descriptions

Field	Description
`date`	Event date (YYYY-MM-DD)
`past_or_future`	Daily time classification: `past` or `future`. This is not a live release status.
`time`	Event time (HH:MM)
`timezone`	Timezone for the event time
`country`	Country associated with the event
`event_name`	Name of the economic event
`volatility`	Impact level (1=low, 2=medium, 3=high)
`actual`	Captured actual value when available. Null may mean unreleased or that no numeric actual value is published.
`forecast`	Consensus forecast value
`previous`	Previous period value
`event_id`	Unique identifier for the event record

Country Codes

Country filters use ISO 3166-1 alpha-2 codes wherever applicable. Use GB for the United Kingdom. EU represents the Euro Zone, while the non-country G20 and G7 groups use XT and XS.

AEUnited Arab Emirates

ALAlbania

AOAngola

ARArgentina

ATAustria

AUAustralia

AZAzerbaijan

BABosnia-Herzegovina

BDBangladesh

BEBelgium

BGBulgaria

BHBahrain

BMBermuda

BRBrazil

BWBotswana

CACanada

CHSwitzerland

CICote D'Ivoire

CLChile

CNChina

COColombia

CRCosta Rica

CYCyprus

CZCzech Republic

DEGermany

DKDenmark

ECEcuador

EEEstonia

EGEgypt

ESSpain

EUEuro Zone

FIFinland

FRFrance

GBUnited Kingdom

GHGhana

GRGreece

HKHong Kong

HRCroatia

HUHungary

IDIndonesia

IEIreland

ILIsrael

INIndia

IQIraq

ISIceland

ITItaly

JMJamaica

JOJordan

JPJapan

KEKenya

KGKyrgyzstan

KRSouth Korea

KWKuwait

KYCayman Islands

KZKazakhstan

LBLebanon

LKSri Lanka

LTLithuania

LULuxembourg

LVLatvia

MAMorocco

MEMontenegro

MNMongolia

MTMalta

MUMauritius

MWMalawi

MXMexico

MYMalaysia

MZMozambique

NANamibia

NGNigeria

NLNetherlands

NONorway

NZNew Zealand

OMOman

PEPeru

PHPhilippines

PKPakistan

PLPoland

PSPalestinian Territory

PTPortugal

PYParaguay

QAQatar

RORomania

RSSerbia

RURussia

RWRwanda

SASaudi Arabia

SESweden

SGSingapore

SISlovenia

SKSlovakia

THThailand

TNTunisia

TRTürkiye

TWTaiwan

TZTanzania

UAUkraine

UGUganda

USUnited States

UYUruguay

UZUzbekistan

VEVenezuela

VNVietnam

XSG7

XTG20

ZASouth Africa

ZMZambia

ZWZimbabwe

Examples

Here are some practical examples to help you get started with common use cases.

Official SDK and API Examples

Official SDKs: floe (TypeScript), floe-go (Go), floe-py (Python).

curl --compressed -H "X-API-Key: hindsight_live_xxxxx" \
  "https://hindsightapi.com/api/getData?start_date=2024-01-01&end_date=2024-03-31&country=US&event=FOMC&min_volatility=2"

Get This Week's (Next 7 Days) Upcoming Economic Prints

Query a 7-day window, then keep only rows marked future using the past_or_future field.

curl -X GET "https://hindsightapi.com/api/getData?start_date=2026-03-18&end_date=2026-03-25&country=US&min_volatility=2" \
  -H "X-API-Key: hindsight_live_xxxxx" \
  | jq 'if type == "array" then .[] | select(.past_or_future == "future") else . end'

If you get an error object instead of an array, lower end_date so it does not exceed your subscription window.

Get All Past FOMC Meeting Dates

Use the event parameter to filter for Federal Open Market Committee events.

curl -X GET "https://hindsightapi.com/api/getData?start_date=2023-01-01&end_date=2023-12-31&event=FOMC&country=US" \
  -H "X-API-Key: hindsight_live_xxxxx"

This returns all events containing FOMC in the event name for 2023.

Get Producer Price Index (PPI) Data

Filter for all PPI-related events in a specific date range.

curl -X GET "https://hindsightapi.com/api/getData?start_date=2024-01-01&end_date=2024-06-30&event=PPI&country=US" \
  -H "X-API-Key: hindsight_live_xxxxx"

This returns PPI, Core PPI, and all other PPI-related events.

High Volatility Employment Data as CSV

Combine multiple filters and get results in CSV format.

curl -X GET "https://hindsightapi.com/api/getData?start_date=2024-01-01&end_date=2024-12-31&event=Employment&min_volatility=3&format=csv" \
  -H "X-API-Key: hindsight_live_xxxxx" \
  -o employment-data-2024.csv

This downloads high-impact employment events as a CSV file.

Error Handling

The API uses standard HTTP status codes:

Code	Description
`200`	Success
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Missing API key
`403`	Forbidden - Invalid or expired API key
`500`	Internal Server Error

Error Response Format

{
  "success": false,
  "error": "Invalid API key"
}

{
    "success": false,
    "error": "Requested end_date exceeds your subscription limit",
    "subscriptionEnd": "2022-03-11"
}

Need Help?

If you have any questions or need assistance, reach out to us at hi@fullstackcraft.com