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

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, UK, 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
  },
  {
    "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
  }
]

CSV Format

Add format=csv to download data as CSV.

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

Field Descriptions

Field	Description
`date`	Event date (YYYY-MM-DD)
`past_or_future`	Temporal marker for the event: `past` or `future`
`time`	Event time (HH:MM)
`timezone`	Timezone for the event time
`country`	Country code (e.g., US, UK, EU)
`event_name`	Name of the economic event
`volatility`	Impact level (1=low, 2=medium, 3=high)
`actual`	Actual reported value (null if not yet released)
`forecast`	Consensus forecast value
`previous`	Previous period value

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 [email protected]