Loading QuantGist...

API Reference

API Reference v1

API Reference

Integrate real-time economic data into your trading systems in minutes.

Base URLhttps://api.quantgist.com/v1

AuthX-API-Keyheader

Get API Key

Introduction

QuantGist is a REST and WebSocket API for real-time and historical economic data — events, calendar releases, earnings, intelligence, and sentiment. Every response is JSON. The base URL is https://api.quantgist.com/v1 and all protected endpoints authenticate via the X-API-Key header.

New here? Grab a key, then make your first request in under five minutes.

Step 1Get an API keyGenerate live or test keys from your dashboard. Step 25-minute QuickstartFetch your first events response with curl or an SDK.

API Keys

Keys come in two flavours: qg_live_<32 chars> for production data and qg_test_<32 chars> for the sandbox. The full key value is shown exactly onceat creation time and is never retrievable again — copy it immediately into a secrets manager.

Manage your keys at /dashboard/keys. Each key shows its prefix (the first 12 characters) so you can identify it without exposing the full value.

Tip:Rotate keys periodically. Store them in environment variables or a secrets manager — never commit them to source control. If a key is compromised, revoke it from the dashboard and generate a replacement.

Sending the header

curl https://api.quantgist.com/v1/events \
  -H "X-API-Key: qg_live_your_key_here"

Quickstart

Five minutes from zero to your first response.

Sign up for a QuantGist account (no card required for the free tier).
Generate an API key from /dashboard/keys — copy the full value the moment it is shown.
Make your first request:

curl "https://api.quantgist.com/v1/events?limit=5" \
  -H "X-API-Key: qg_live_your_key_here"

Install an SDK

Official client libraries handle pagination, retries, and typed responses.

pip install quantgist

Source: Python SDK · JavaScript SDK

Trader-friendly macro shortcuts

Skip the event search: use /v1/macro/* to fetch well-known releases by name. Supported aliases: NFP, CPI, PCE, FOMC, GDP, UNEMPLOYMENT, RETAIL_SALES, PPI, ISM, ECB, HICP.

bash

# Latest released NFP value
curl 'https://api.quantgist.com/v1/macro/latest?event=NFP' \
  -H 'X-API-Key: YOUR_KEY'

# Next scheduled CPI release
curl 'https://api.quantgist.com/v1/macro/upcoming?event=CPI' \
  -H 'X-API-Key: YOUR_KEY'

# Grouped calendar: CPI, NFP, and FOMC in the next 14 days
curl 'https://api.quantgist.com/v1/macro/calendar?events=CPI,NFP,FOMC&days=14' \
  -H 'X-API-Key: YOUR_KEY'

Note:Next: read about authentication or jump straight to the Events endpoint.

Authentication

All API requests must include your API key in the X-API-Key HTTP header. Generate and manage keys from your dashboard.

curl https://api.quantgist.com/v1/events \
  -H "X-API-Key: qg_live_your_key_here"

Authentication errors

Field	Type	Description
`401`	Unauthorized	No API key supplied, or the key format is invalid.
`403`	Forbidden	Valid key, but your plan does not include this endpoint.
`429`	Too Many Requests	Daily or per-minute rate limit exceeded. Check X-RateLimit-* response headers.

Events

Returns a paginated list of economic events matching your filters.

ENDPOINT|GET/v1/events#

Note:Free-plan responses carry a 15-minute delay. Upgrade to Starter or above for near real-time data.

Query parameters

Param	Type	Req	Description
`symbol`	string	—	Filter by ticker symbol (e.g. EURUSD, SPX). Comma-separated for multiple.
`currency`	string	—	ISO 4217 currency code (e.g. USD, EUR).
`impact`	string	—	Event impact level: low \| medium \| high.
`event_type`	string	—	Type of event: earnings \| fomc \| cpi \| nfp \| gdp \| pmi \| other.
`from_date`	ISO 8601	—	Start of date range (inclusive). e.g. 2024-01-01T00:00:00Z.
`to_date`	ISO 8601	—	End of date range (inclusive).
`q`	string	—	Free-text search across event title and description.
`page`	integer	—	Page number, 1-indexed. Default: 1.
`page_size`	integer	—	Results per page (max 100). Default: 20.

Example response

json

{
  "data": [
    {
      "id": "evt_01HX9M3K4R2BGCZ8JQNVP7YW5E",
      "event_type": "nfp",
      "title": "US Non-Farm Payrolls (Mar 2024)",
      "currency": "USD",
      "impact": "high",
      "release_time": "2024-04-05T12:30:00Z",
      "actual": 303000,
      "forecast": 214000,
      "previous": 270000,
      "surprise_pct": 41.6,
      "sentiment_score": 0.82
    }
  ],
  "meta": {
    "page": 1,
    "page_size": 20,
    "total": 1842,
    "has_more": true
  }
}

Single Event

Fetch the full event object including all fields and historical revisions.

ENDPOINT|GET/v1/events/{event_id}#

Response schema

Field	Type	Description
`id`	string	Unique event identifier (ULID format).
`event_type`	string	Category: earnings \| fomc \| cpi \| nfp \| gdp \| pmi \| other.
`title`	string	Human-readable event title.
`currency`	string	Primary currency affected (ISO 4217).
`symbol`	string \| null	Primary ticker symbol if applicable.
`impact`	string	Assessed market impact: low \| medium \| high.
`release_time`	ISO 8601	Scheduled or actual release timestamp (UTC).
`actual`	number \| null	Actual reported value.
`forecast`	number \| null	Consensus forecast prior to release.
`previous`	number \| null	Prior period value (may be revised).
`surprise_pct`	number \| null	Percentage surprise vs. forecast.
`sentiment_score`	number \| null	NLP-derived market sentiment −1 to +1. Pro+ only.
`impact_score`	number \| null	Deterministic 0–1 score combining impact level, event type, and keyword cues. Beta, may be null for some events.
`summary`	string \| null	One-line plain-text summary of the event. Beta, template-generated, may be null for some events.
`tags`	string[]	Semantic tags for topic classification.

Beta fields: summary and impact_score are in beta and may be null for some events. Coverage is highest for recent high-impact economic releases; news headlines and IPOs are not summarised at launch.

Historical Data

Bulk-download historical events. Supports NDJSON format for streaming large datasets efficiently.

ENDPOINT|GET/v1/events/historical#

Warning:NDJSON bulk download requires an Enterprise plan. Lower plans are limited to standard paginated JSON.

Query parameters

Param	Type	Req	Description
`from_date`	ISO 8601	yes	Start of range.
`to_date`	ISO 8601	yes	End of range (max 365-day window).
`symbol`	string	—	Ticker symbol filter (comma-separated).
`currency`	string	—	ISO 4217 currency code.
`format`	string	—	Response format: json (default) \| ndjson.
`page`	integer	—	Page number for JSON format. Default: 1.

bash

curl "https://api.quantgist.com/v1/events/historical?from_date=2024-01-01&to_date=2024-03-31&format=ndjson" \
  -H "X-API-Key: qg_live_your_key_here" \
  --output events.ndjson

Calendar

Returns today's economic calendar. Defaults to UTC date if no date is supplied.

ENDPOINT|GET/v1/calendar#

Param	Type	Req	Description
`date`	YYYY-MM-DD	—	Calendar date. Defaults to today (UTC).
`currency`	string	—	Filter to one or more currencies.
`impact`	string	—	Minimum impact level: low \| medium \| high.
`include_actual`	boolean	—	Include actual values for past events. Default: true.

Example response

json

{
  "date": "2024-04-23",
  "events": [
    {
      "id": "evt_01HX9...",
      "title": "Fed Interest Rate Decision",
      "currency": "USD",
      "impact": "high",
      "release_time": "2024-04-23T18:00:00Z",
      "forecast": 5.5,
      "actual": null,
      "previous": 5.5
    }
  ],
  "count": 14
}

Calendar Range

Returns the economic calendar for a multi-day range. Both date_from and date_to are required.

ENDPOINT|GET/v1/calendar/range#

Param	Type	Req	Description
`date_from`	YYYY-MM-DD	yes	Start date of the range (inclusive).
`date_to`	YYYY-MM-DD	yes	End date of the range (inclusive, max +30 days).
`currency`	string	—	Currency filter.
`impact`	string	—	Minimum impact: low \| medium \| high.

Macro Shortcuts

Trader-friendly convenience layer on top of /v1/events and /v1/calendar. Reference well-known macro releases by alias (e.g. NFP, CPI) without knowing the exact event title or ID.

ENDPOINT|GET/v1/macro/events#

List all supported macro aliases and their canonical event types.

ENDPOINT|GET/v1/macro/latest#

Most recent released row for the given alias. Query param: event (e.g. NFP).

ENDPOINT|GET/v1/macro/upcoming#

Next scheduled release for the given alias. Query param: event (e.g. CPI).

ENDPOINT|GET/v1/macro/calendar#

Grouped upcoming releases for multiple aliases. Query params: events (comma-separated), days (default 14).

Supported aliases: NFP, CPI, PCE, FOMC, GDP, UNEMPLOYMENT, RETAIL_SALES, PPI, ISM, ECB, HICP.

bash

# Latest released NFP
curl 'https://api.quantgist.com/v1/macro/latest?event=NFP' \
  -H 'X-API-Key: YOUR_KEY'

# Next CPI release
curl 'https://api.quantgist.com/v1/macro/upcoming?event=CPI' \
  -H 'X-API-Key: YOUR_KEY'

# CPI + NFP + FOMC calendar for the next 14 days
curl 'https://api.quantgist.com/v1/macro/calendar?events=CPI,NFP,FOMC&days=14' \
  -H 'X-API-Key: YOUR_KEY'

# All supported aliases
curl 'https://api.quantgist.com/v1/macro/events' \
  -H 'X-API-Key: YOUR_KEY'

Backtesting with canonical events

Do not use ?q=CPI for backtesting — free-text search is a noisy substring match that can return unrelated events, wrong vintages, or rows without actual values. Use the dedicated /v2/backtest contract with canonical_id and check /v2/backtest/coverage before treating a series as strategy-ready.

bash

# Canonical CPI history, strict v2 backtest contract
GET /v2/backtest?canonical_id=US_CPI_YOY&from_date=2020-01-01&to_date=2026-01-01

# Readiness gate before allocating research compute
GET /v2/backtest/coverage?canonical_id=US_CPI_YOY

# Raw export only; do not use this as the macro backtesting contract
GET /v1/events/historical?from_date=2025-01-01&to_date=2025-01-31&format=ndjson

Note:Use /v1/macro/latest for latest display values, /v1/events/historical for raw NDJSON export, /v2/backtest for first-print backtest rows, and as_of on v2 when you need the value known at a historical cutoff.

News Live

Choosing the right news surface

/v1/news— Raw headline feed. Paginated stream of ingested headlines from Bloomberg, WSJ, CNBC, NYT, Yahoo Finance, GDELT, and Alpha Vantage. Use this when you want to read or search news; filter with ?q=, symbol, or currency. Each row carries a summary, optional topic_matches, and a low-confidence impact_score on a per-headline basis.

/v1/news/radar— Clustered + scored trade intelligence. Groups related headlines into a single event cluster, attaches a topic pack, and scores the cluster against severity, novelty, asset linkage, and corroboration. Returns impact_score, confidence, affected_assets, why_it_matters, and lifecycle status. Designed for traders watching a risk theme rather than reading headlines.

Tip:For unplanned market shocks (Iran/Hormuz, OPEC surprise cuts, emergency rate moves, ransomware on critical infrastructure) prefer /v1/news/radar?topic=<slug> or a watchlist subscription — not raw /v1/news?q=... alone. Raw keyword search returns single-source headlines without corroboration or scoring; it is great for reading, but it will not tell you that eight outlets in twenty minutes just confirmed the same event.

Sample queries

bash

# Raw headlines about Iran/war: readable feed, single-source rows
GET /v1/news?q=iran%20war&per_page=10

Returns headlines with summary, summary_source, topic_matches, and a per-headline impact_score capped low for single-source rows.

bash

# Clustered Iran-conflict trade intelligence above an alert threshold
GET /v1/news/radar?topic=iran-war&min_impact=0.5

Returns clustered events with impact_score, affected_assets, why_it_matters, and a lifecycle status.

bash

# Oil-supply disruption clusters (OPEC, pipelines, refineries, Hormuz)
GET /v1/news/radar?topic=oil-supply&min_impact=0.5

Returns supply-shock clusters — matches require both an energy-context term and a disruption term (see Topic evidence gate below), so a generic “explosion” headline will not score here.

bash

# Earnings history for a ticker
GET /v1/earnings/AAPL?limit=12

Returns up to 12 most recent earnings rows with EPS actual/estimate/surprise, fiscal period, and per-field provenance in field_sources.

Topic evidence gate

News Radar topic matches now require two pieces of evidence before a headline can be assigned to a topic pack: at least one topic-context term (what subject the headline is about) and at least one disruption/event term (what is happening). For example, the oil-supply pack requires an energy term such as oil, refinery, pipeline, OPEC, or Hormuz and a disruption term such as shutdown, outage, attack, or production cut. Headlines that only carry a generic high-severity word (e.g. “Blue Origin rocket explosion”) no longer attach to oil-supply, which removes a category of false-positive alerts.

News summary semantics

Every row on /v1/news exposes a summary_source field so you can trust or discount the summary appropriately:

Field	Type	Description
`source`	string	Summary came from the publisher (Alpha Vantage news, vendor RSS body). Faithfully reflects the article.
`rule_template`	string	Deterministic 1-sentence fallback we generate from title + matched topic + affected assets when the publisher provided no summary. No facts beyond the headline.
`none`	string	No usable title or template input, summary is null.

News Radar topic packs — quick reference

Topic slug	Description
`iran-war`	Iran military conflict and Hormuz shipping risk
`oil-supply`	OPEC+ cuts, pipeline outages, supply disruptions
`sanctions`	New or lifted economic sanctions
`central-bank-unscheduled`	Emergency / unscheduled central bank rate moves
`trump-posts`	Trump social-media policy announcements
`middle-east-risk`	Broader Middle East geopolitical escalation
`cyberattack`	Major infrastructure or financial-sector cyber incidents
`ceasefire`	Ceasefire announcements and de-escalation signals
`opec`	OPEC/OPEC+ production decisions and compliance reports

bash

# Unscheduled geopolitical risk: Iran conflict clusters, high-impact only
GET /v1/news/radar?topic=iran-war&min_impact=0.6&limit=10

# Emergency central-bank moves (surprise rate cuts/hikes)
GET /v1/news/radar?topic=central-bank-unscheduled&limit=5

# Raw keyword search across all headlines
GET /v1/news?q=OPEC&currency=USD&impact=high

Retrieves structured financial news headlines aggregated from Bloomberg, WSJ, CNBC, NYT, and Yahoo Finance. Headlines are ingested every 20 minutes and tagged by currency, symbol, and impact.

ENDPOINT|GET/v1/news#

Param	Type	Req	Description
`source`	string	—	Filter by news source identifier.
`currency`	string	—	Currency mentioned in the article.
`symbol`	string	—	Ticker symbol referenced.
`impact`	string	—	Assessed impact: low \| medium \| high.
`q`	string	—	Full-text search across title and body.
`page`	integer	—	Page number. Default: 1.

json

{
  "data": [
    {
      "id": "...",
      "event_type": "news_headline",
      "source": "rss_news",
      "title": "Fed Holds Rates Steady as Officials Weigh Inflation Path",
      "summary": "Federal Reserve officials held interest rates steady and signalled they remain cautious about cutting borrowing costs.",
      "published_at": "2026-05-25T14:30:00Z",
      "source_url": "https://www.wsj.com/articles/fed-holds-rates-steady-...",
      "currency": "USD",
      "symbols": ["SPY", "TLT"],
      "sentiment_score": -0.12,
      "sentiment_label": "bearish",
      "impact": "high"
    }
  ],
  "total": 200,
  "page": 1,
  "per_page": 5
}

News Radar Live

Scored, asset-linked market-risk clusters built by grouping raw headlines under a topic pack (e.g. iran-war, oil-supply, sanctions). Each cluster carries an impact_score in [0, 1], an affected_assets ticker list, and a lifecycle status, designed for traders subscribed to a topic rather than searching raw headlines. Free plan: 10 reads/day. Starter+: unlimited.

ENDPOINT|GET/v1/news/radar#

Param	Type	Req	Description
`topic`	string	—	Topic slug (e.g. iran-war). See /v1/news/topics.
`symbols`	string	—	Comma-separated tickers; match any (e.g. USO,GLD,SPY).
`min_impact`	number	—	Minimum impact_score in [0, 1]. Default 0.0.
`event_type`	string	—	geopolitical_risk \| supply_shock \| policy_shock \| cyber \| de_escalation \| supply_policy.
`status`	string	—	developing \| breaking \| fading \| resolved.
`lookback_hours`	integer	—	Window over latest_seen. Default 72, max 720.
`limit`	integer	—	Max clusters returned. Default 50, max 200.

json

{
  "items": [
    {
      "id": "9c3e1a4f-...",
      "topic": "iran-war",
      "headline": "Iran strikes oil facility in coordinated drone attack",
      "why_it_matters": "Active Iran conflict threatens the Strait of Hormuz, the chokepoint for ~20% of global seaborne oil...",
      "impact_score": 0.82,
      "confidence": 0.76,
      "affected_assets": ["CL", "USO", "XLE", "GLD", "XAUUSD"],
      "affected_assets_source": "llm",
      "event_type": "geopolitical_risk",
      "status": "breaking",
      "source_count": 8,
      "first_seen": "2026-05-27T11:14:00Z",
      "latest_seen": "2026-05-27T14:02:00Z"
    }
  ],
  "total": 1,
  "min_impact": 0.65,
  "lookback_hours": 72
}

News Topics Live

Catalogue of supported News Radar topic packs. Each pack carries its affected tickers and asset-class breakdown so callers can build a watchlist without a second request. Available packs include iran-war, middle-east-risk, oil-supply, sanctions, trump-posts, central-bank-unscheduled, cyberattack, ceasefire, and opec.

ENDPOINT|GET/v1/news/topics#

json

{
  "items": [
    {
      "slug": "iran-war",
      "display_name": "Iran War Risk",
      "description": "Military conflict, sanctions tightening, or escalation rhetoric involving Iran...",
      "event_type": "geopolitical_risk",
      "affected_assets": ["CL", "USO", "XLE", "GLD", "XAUUSD", "SPY", "DAL", "LMT", "..."],
      "affected_asset_classes": {
        "oil": ["CL", "USO", "XLE", "BNO", "XOP"],
        "safe_haven": ["GLD", "XAUUSD", "USDJPY", "USDCHF", "TLT"],
        "defense": ["LMT", "RTX", "NOC", "BA", "GD", "ITA"]
      },
      "related_topics": ["middle-east-risk", "oil-supply"]
    }
  ],
  "total": 9
}

News Watchlists Starter+

Subscribe to News Radar topic packs. When a new cluster is scored above your min_impact threshold an alert is created automatically. Manage subscriptions with GET / POST / DELETE on /v1/news/watchlists.

ENDPOINT|GET/v1/news/watchlists#

json

{
  "items": [
    {
      "id": "e2a1f3b4-0000-0000-0000-000000000001",
      "topic_slug": "iran-war",
      "min_impact": 0.5,
      "created_at": "2026-05-28T10:00:00Z"
    }
  ],
  "total": 1
}

ENDPOINT|POST/v1/news/watchlists#

Subscribe to a topic pack. Returns 409 if already subscribed.

Param	Type	Req	Description
`topic_slug`	string	yes	Topic pack slug (e.g. iran-war). See /v1/news/topics.
`min_impact`	number	—	Min impact_score [0, 1] to trigger an alert. Default 0.5.

ENDPOINT|DELETE/v1/news/watchlists/{topic_slug}#

Unsubscribe from a topic pack. Cascades to all associated alerts. Returns 204 No Content.

Param	Type	Req	Description
`topic_slug`	string	yes	The topic pack slug to unsubscribe from (path parameter).

News Alerts Starter+

Alerts are created automatically when a new cluster crosses your watchlist min_impact threshold. Fetch unread alerts, acknowledge individual ones, or clear all in one shot.

ENDPOINT|GET/v1/news/alerts#

Param	Type	Req	Description
`unread_only`	boolean	—	Only return unread alerts (acked_at is null). Default true.
`limit`	integer	—	Max alerts to return (1–200). Default 50.

json

{
  "items": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "topic_slug": "iran-war",
      "acked_at": null,
      "created_at": "2026-05-28T11:00:00Z",
      "cluster": {
        "headline": "Iran drones target oil facility near Kharg Island",
        "impact_score": 0.85,
        "status": "breaking",
        "why_it_matters": "Escalation near Kharg Island threatens ~90% of Iran's oil export capacity...",
        "why_it_matters_source": "llm",
        "affected_assets": ["USO", "CL", "XLE", "GLD"],
        "affected_assets_source": "llm"
      }
    }
  ],
  "total": 3,
  "unread_only": true
}

ENDPOINT|POST/v1/news/alerts/{alert_id}/ack#

Mark a single alert as read. Returns the updated alert object with acked_at set.

Param	Type	Req	Description
`alert_id`	string	yes	Alert UUID (path parameter).

ENDPOINT|POST/v1/news/alerts/ack-all#

Mark all unread alerts as read. Returns a count of acknowledged alerts.

json

{ "acked": 5 }

Symbols

Reference data for all supported ticker symbols and currency pairs.

ENDPOINT|GET/v1/symbols#

Param	Type	Req	Description
`q`	string	—	Search by symbol or name.
`currency`	string	—	Filter by base currency.

json

{
  "data": [
    {
      "symbol": "EURUSD",
      "name": "Euro / US Dollar",
      "category": "forex",
      "base_currency": "EUR",
      "quote_currency": "USD",
      "exchange": "FX"
    }
  ],
  "total": 312
}

Earnings

Earnings data sourced from Alpha Vantage (upcoming calendar + per-ticker EPS history) and enriched with SEC EDGAR 8-K filing links where available. Every confirmed event includes EPS actuals vs. estimates and a direct URL to the corresponding 8-K filing on sec.gov.

Note:/v1/earnings/{ticker}/history requires Pro or above. Historical bulk NDJSON export (/v1/earnings/historical) requires Enterprise. Per-ticker history coverage is currently mega-caps + the top 200 US tickers (curated list).

Warning:Coverage caveats. Alpha Vantage supplies EPS coverage (actual, estimate, surprise) and the fiscal calendar. Revenue actuals/estimates, SEC filing links, options-implied move, and price reaction depend on separate enrichment jobs and may be null in current responses; they are not a sign the row is broken. Every populated field carries a per-field origin in field_sources (e.g. fmp, sec_edgar, derived_from_fiscal_date_ending), and the row-level currency_source distinguishes publisher-supplied currencies from inferred_us_listing fallbacks.

Endpoints

ENDPOINT|GET/v1/earnings#

Paginated list of recent earnings events. Filter by ticker, date range, or beat/miss.

ENDPOINT|GET/v1/earnings/upcoming#

Earnings events scheduled in the next 30 days.

ENDPOINT|GET/v1/earnings/{ticker}#

Most recent earnings event for a specific ticker.

ENDPOINT|GET/v1/earnings/{ticker}/summary#

Aggregated beat/miss statistics for a ticker.

ENDPOINT|GET/v1/earnings/{ticker}/history#

Full historical earnings series for a ticker. Pro+ only.

ENDPOINT|GET/v1/earnings/surprises#

Top EPS and revenue surprises from the last 30 days.

ENDPOINT|GET/v1/earnings/movers#

Stocks with the largest post-earnings price moves.

ENDPOINT|GET/v1/earnings/calendar/week#

Earnings calendar for the current or a specified week.

ENDPOINT|GET/v1/earnings/calendar.ics#

iCalendar (.ics) feed, subscribe in Google Calendar / Outlook.

ENDPOINT|GET/v1/earnings/season/summary#

Aggregate beat rate, sector breakdown, and key stats for the active earnings season.

EarningsEventResponse schema

Field	Type	Description
`id`	string	Unique event identifier (ULID).
`ticker`	string	Equity ticker symbol (e.g. AAPL).
`company_name`	string	Issuing company name.
`report_date`	ISO 8601	Date of earnings release.
`fiscal_quarter`	string	Fiscal quarter reported (e.g. Q1 2025).
`eps_actual`	number \| null	Reported EPS.
`eps_estimate`	number \| null	Consensus EPS estimate.
`eps_surprise_pct`	number \| null	EPS surprise as a percentage.
`revenue_actual`	number \| null	Reported revenue (USD).
`revenue_estimate`	number \| null	Consensus revenue estimate (USD).
`sec_filing_url`	string \| null	Direct URL to the SEC EDGAR 8-K filing.
`sec_accession_number`	string \| null	SEC EDGAR accession number for the filing.
`sec_filed_at`	ISO 8601 \| null	Timestamp the 8-K was filed with the SEC.
`field_sources`	object	Per-field provenance map, indicates whether each field came from SEC EDGAR, yfinance, or another source.

Example response

json

{
  "id": "earn_01HX9M3K4R2BGCZ8JQNV",
  "ticker": "AAPL",
  "company_name": "Apple Inc.",
  "report_date": "2025-05-01",
  "fiscal_quarter": "Q2 2025",
  "eps_actual": 1.65,
  "eps_estimate": 1.61,
  "eps_surprise_pct": 2.48,
  "revenue_actual": 95370000000,
  "revenue_estimate": 94460000000,
  "sec_filing_url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000051/0000320193-25-000051-index.htm",
  "sec_accession_number": "0000320193-25-000051",
  "sec_filed_at": "2025-05-01T20:05:00Z",
  "field_sources": {
    "eps_actual": "sec_edgar",
    "revenue_actual": "sec_edgar",
    "eps_estimate": "yfinance"
  }
}

Market Overview

Cached daily quote snapshots for indexes (SPY, QQQ, DIA), large-cap equities (AAPL, MSFT, GOOGL, NVDA, AMZN), and commodities (GLD, USO). Sourced from Alpha Vantage. The last_refreshed_at field on every item exposes the actual snapshot time so you can surface freshness to your users; recency reports "delayed_15m" for fresh snapshots and "stale" when serving a 24-hour fallback. Higher refresh frequency is on the roadmap.

Note:Snapshots are never fetched on the hot request path. Responses come from the DB + Redis cache. Each item includes provider, last_refreshed_at, and stale fields so you can surface data freshness to your users.

Endpoints

ENDPOINT|GET/v1/markets/overview#

All tracked groups (indexes, equities, commodities) in one response.

ENDPOINT|GET/v1/markets/indexes#

Cached daily snapshot of US index ETFs (SPY, QQQ, DIA).

ENDPOINT|GET/v1/markets/equities#

Cached daily snapshot of tracked large-cap equities.

ENDPOINT|GET/v1/markets/sectors#

Sector ETF performance, returns empty list until extended coverage is seeded.

ENDPOINT|GET/v1/markets/currencies#

FX rates, returns empty list until extended coverage is seeded.

ENDPOINT|GET/v1/markets/commodities#

Cached daily snapshot of commodity ETFs (GLD, USO).

ENDPOINT|GET/v1/markets/{symbol}#

Latest cached snapshot for any symbol in the DB.

Changelog

Returns a JSON array of API changes in reverse chronological order. Public, no authentication required.

ENDPOINT|GET/v1/changelog#

Tip:No X-API-Key header needed for this endpoint. Suitable for status pages and SDK auto-update checks.

bash

curl https://api.quantgist.com/v1/changelog

Example response

json

[
  {
    "version": "1.5.0",
    "date": "2025-05-01",
    "summary": "Earnings API: 10 new endpoints including SEC EDGAR provenance",
    "breaking": false
  },
  {
    "version": "1.4.0",
    "date": "2025-04-10",
    "summary": "Market Overview endpoints: cached quote snapshots via Alpha Vantage",
    "breaking": false
  }
]

Real-time WebSocket

Subscribe to a live event stream. The server sends a snapshot of recent events on connect, then pushes new events as they are published.

WSwss://api.quantgist.com/v1/stream

Tip:Authenticate via the ?api_key=qg_live_… query parameter. The X-API-Key header is not forwarded by browser WebSocket clients.

javascript

const ws = new WebSocket(
  "wss://api.quantgist.com/v1/stream?api_key=qg_live_your_key_here"
);

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: "subscribe",
    currencies: ["USD", "EUR"],
    impact: ["high"]
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === "snapshot") {
    console.log("Initial snapshot:", msg.events);
  } else if (msg.type === "event") {
    console.log("New event:", msg.data);
  }
};

Field	Type	Description
`type`	string	"snapshot" on connect, "event" for live updates, "ping" for keep-alive.
`events`	Event[]	Included in snapshot messages only.
`data`	Event	Single event object in live update messages.
`ts`	ISO 8601	Server-side timestamp of the message.

Intelligence: Surprises

Starter+

Recent economic releases ranked by surprise magnitude (how far actual values deviated from forecast). Positive scores beat expectations, negative scores missed.

ENDPOINT|GET/v1/intelligence/surprises#

Param	Type	Req	Description
`hours`	integer	—	Look-back window in hours (1–168). Default: 24.
`limit`	integer	—	Max number of results (1–100). Default: 20.
`currency`	string	—	Filter by ISO currency code (e.g. USD).
`min_impact`	string	—	Minimum impact level: low \| medium \| high.

bash

curl "https://api.quantgist.com/v1/intelligence/surprises?hours=24&min_impact=high" \
  -H "X-API-Key: qg_live_your_key_here"

Intelligence: Movers

Events ranked by expected market-impact potential, a composite of impact level, event category importance, and recent surprise magnitude.

ENDPOINT|GET/v1/intelligence/movers#

Param	Type	Req	Description
`hours`	integer	—	Look-back window in hours (1–168). Default: 24.
`limit`	integer	—	Max number of results (1–100). Default: 20.
`currency`	string	—	ISO currency code filter.
`min_score`	number	—	Drop events below this composite mover score.

bash

curl "https://api.quantgist.com/v1/intelligence/movers?currency=USD&limit=10" \
  -H "X-API-Key: qg_live_your_key_here"

Sentiment Summary

Starter+

Aggregate sentiment statistics grouped by a chosen dimension (currency, country, event_type, or sector).

ENDPOINT|GET/v1/sentiment/summary#

Param	Type	Req	Description
`group_by`	string	—	Dimension: currency \| country \| event_type \| sector.
`hours`	integer	—	Look-back window in hours. Default: 24.
`min_impact`	string	—	Minimum event impact: low \| medium \| high.

bash

curl "https://api.quantgist.com/v1/sentiment/summary?group_by=currency&hours=48" \
  -H "X-API-Key: qg_live_your_key_here"

Sentiment: Events

Paginated list of events filtered and sorted by sentiment score.

ENDPOINT|GET/v1/sentiment/events#

Param	Type	Req	Description
`label`	string	—	Sentiment label: positive \| neutral \| negative.
`min_score`	number	—	Minimum sentiment score (-1 to 1).
`max_score`	number	—	Maximum sentiment score (-1 to 1).
`currency`	string	—	ISO currency code filter.
`from_date`	ISO 8601	—	Start of date range.
`to_date`	ISO 8601	—	End of date range.
`page`	integer	—	Page number. Default: 1.
`page_size`	integer	—	Results per page (max 100). Default: 20.

bash

curl "https://api.quantgist.com/v1/sentiment/events?label=negative&min_score=-1&max_score=-0.4" \
  -H "X-API-Key: qg_live_your_key_here"

Data Export

Stream a compressed bulk export of events for a specified date range.

ENDPOINT|GET/v1/data/export#

Warning:Bulk export is available on Pro and above. Supports NDJSON and CSV formats.

Param	Type	Req	Description
`from_date`	ISO 8601	yes	Start of range (inclusive).
`to_date`	ISO 8601	yes	End of range (inclusive).
`format`	string	—	ndjson (default) \| csv.
`currency`	string	—	ISO currency code filter.

bash

curl "https://api.quantgist.com/v1/data/export?from_date=2024-01-01&to_date=2024-03-31&format=ndjson" \
  -H "X-API-Key: qg_live_your_key_here" \
  --output events.ndjson

Data Packs

Pre-built historical bundles. The catalogue is public; downloads require Pro+.

ENDPOINT|GET/v1/data/packs#

List all available data packs. No authentication required.

ENDPOINT|GET/v1/data/packs/{pack_id}/download#

Stream a pack as NDJSON. Pro+ required.

Organizations

Multi-seat workspaces with shared usage quotas. Create orgs, manage members, and invite teammates.

ENDPOINT|POST/v1/organizations#

Create a new organization.

ENDPOINT|GET/v1/organizations#

List organizations the authenticated user belongs to.

ENDPOINT|GET/v1/organizations/{org_id}#

Fetch a single organization.

Organization Members

ENDPOINT|POST/v1/organizations/{org_id}/members#

ENDPOINT|GET/v1/organizations/{org_id}/members#

ENDPOINT|DELETE/v1/organizations/{org_id}/members/{user_id}#

ENDPOINT|GET/v1/organizations/{org_id}/usage#

Organization Invites

ENDPOINT|POST/v1/organizations/{org_id}/invites#

ENDPOINT|GET/v1/organizations/{org_id}/invites#

ENDPOINT|POST/v1/organizations/invites/accept#

Webhooks

Pro+

ENDPOINT|POST/v1/webhooks#

ENDPOINT|GET/v1/webhooks#

ENDPOINT|PUT/v1/webhooks/{endpoint_id}#

ENDPOINT|DELETE/v1/webhooks/{endpoint_id}#

ENDPOINT|POST/v1/webhooks/{endpoint_id}/test#

ENDPOINT|GET/v1/webhooks/branding#

ENDPOINT|PUT/v1/webhooks/branding#

Notifications

ENDPOINT|POST/v1/notifications/channels#

ENDPOINT|GET/v1/notifications/channels#

ENDPOINT|GET/v1/notifications/channels/{channel_id}#

ENDPOINT|PUT/v1/notifications/channels/{channel_id}#

ENDPOINT|DELETE/v1/notifications/channels/{channel_id}#

Send Test Notification

Dispatch a synthetic test message to a channel to verify it is correctly configured.

ENDPOINT|POST/v1/notifications/channels/{channel_id}/test#

SLA Status

Public

Returns the last 30 days of pre-computed SLA metrics (uptime, ingestion latency, freshness). No authentication required.

ENDPOINT|GET/v1/sla/status#

bash

curl https://api.quantgist.com/v1/sla/status

Usage Stats

Returns your current API usage statistics and plan limits for today.

ENDPOINT|GET/v1/usage#

json

{
  "plan": "pro",
  "period": "2024-04-23",
  "requests": {
    "today": 1204,
    "limit": 50000,
    "remaining": 48796,
    "reset_at": "2024-04-24T00:00:00Z"
  },
  "rate_limit": {
    "per_minute": 120,
    "remaining_this_minute": 117
  }
}

Auth Endpoints

Manage user accounts and API keys at https://api.quantgist.com/auth.

ENDPOINT|POST/auth/register#

Create a new account. Returns a JWT access token and initial API key.

Param	Type	Req	Description
`email`	string	yes	User email address.
`password`	string	yes	Min 8 characters.
`name`	string	—	Display name.

ENDPOINT|POST/auth/login#

Exchange credentials for a JWT access token.

Param	Type	Req	Description
`email`	string	yes	Registered email address.
`password`	string	yes	Account password.

ENDPOINT|GET/auth/keys#

List all API keys for the authenticated user (key values are masked).

ENDPOINT|DELETE/auth/keys/{id}#

Permanently revoke an API key. This action cannot be undone.

Billing

Manage subscriptions via Stripe. Requires a JWT Bearer token.

ENDPOINT|POST/billing/checkout#

Start a Stripe Checkout session to upgrade your plan. Returns a redirect URL.

Param	Type	Req	Description
`plan`	string	yes	Target plan: starter \| pro \| team.
`annual`	boolean	—	Annual billing (2 months free). Default: false.

ENDPOINT|POST/billing/portal#

Open the Stripe Customer Portal to manage or cancel your subscription.

ENDPOINT|GET/billing/subscription#

Return the authenticated user's current plan and billing status.

Google OAuth

Sign in or sign up using a Google account. The browser is redirected to Google's consent screen, and the callback exchanges the code for a session and initial API key.

ENDPOINT|GET/v1/auth/google#

Redirect the browser to Google's OAuth 2.0 consent screen.

ENDPOINT|GET/v1/auth/google/callback#

Exchange the authorization code for a user record. Redirects to /auth/callback?key=&token=&new_user=.

Error Codes

All error responses follow a consistent JSON structure:

json

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "You have exceeded your daily request quota.",
    "status": 429,
    "docs": "https://quantgist.com/docs#error-codes"
  }
}

Code	Status	Meaning
`400`	Bad Request	The request was malformed or a required parameter is missing.
`401`	Unauthorized	No API key provided, or the key is invalid / expired.
`403`	Forbidden	Your plan does not include this endpoint or feature.
`404`	Not Found	The requested resource does not exist.
`422`	Unprocessable Entity	Validation failed. Check the errors array for field-level details.
`429`	Too Many Requests	Rate limit or daily quota exceeded. Retry after X-RateLimit-Reset.
`503`	Service Unavailable	Temporary maintenance. Check status.quantgist.com for updates.

Rate Limits

The API enforces both a per-minute burst limit and a per-day quota. Each plan has a different ceiling. Successful responses include three headers so clients can self-throttle without retrying blindly.

Field	Type	Description
`X-RateLimit-Limit`	integer	Maximum requests allowed in the current window.
`X-RateLimit-Remaining`	integer	Requests remaining before the next reset.
`X-RateLimit-Reset`	unix timestamp	When the current window resets (seconds since epoch).

Note:When you exceed a limit the response is 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying. The official SDKs honour this header automatically.

Plan Limits

Each plan gates feature access and quota. Calls to endpoints outside your plan return 403 Forbidden; calls beyond your daily quota return 429 Too Many Requests.

Field	Type	Description
`Free`	100 req/day	15-minute delayed data. 1-year history. Events, calendar, symbols.
`Starter`	5,000 req/day	Near real-time data. 3-year history. Adds intelligence and sentiment.
`Pro`	50,000 req/day	Real-time. 10-year history. Adds webhooks, bulk NDJSON export, and per-ticker earnings history.
`Team`	250,000 req/month	Real-time. 730-day history. Unlimited watchlists, up to 10 WS connections.
`Enterprise`	unlimited	Real-time. Unlimited history. Custom SLA, dedicated support.

Tip:Compare plans and upgrade from /pricing or directly inside the dashboard billing page.

v2 Backtesting Mode

The /v2 namespace adds research-quality historical data with point-in-time query support. The public macro backtesting contract is /v2/backtest; raw v1 exports are not strategy-ready. Four safety flags restrict results to data that was actually published and known at a given point in time:

Field	Type	Description
`released_only`	bool	Exclude events with release_time in the future (calendar rows you cannot trade on yet).
`actual_required`	bool	Exclude events where actual is null (awaiting official figures).
`official_only`	bool	Restrict to official-source adapters (BLS, BEA, FRED, ECB, ONS). Excludes ForexFactory / Investing aggregators.
`first_print_only`	bool	Return the first-published value for each event, not the latest revision. Prevents look-ahead bias from later revisions.

The /v2/backtest endpoint enforces all four flags and uses strict=true by default. If a requested canonical_id does not pass coverage gates, strict mode fails closed instead of returning a partial dataset:

ENDPOINT|GET/v2/backtest#

Param	Type	Req	Description
`canonical_id`	string	—	Canonical event ID (e.g. US_CPI_YOY, US_NFP).
`currency`	string	—	ISO 4217 currency filter.
`country`	string	—	ISO 3166-1 alpha-2 country filter.
`impact`	string	—	high \| medium \| low
`from_date`	ISO 8601	—	Start of date range. Defaults to 2 years ago.
`to_date`	ISO 8601	—	End of date range.
`as_of`	ISO 8601	—	Return the value as it was known on this date. Enables point-in-time queries.
`strict`	boolean	—	Default true. Fails closed when the requested canonical ID is not backtest-grade. Set false only for exploratory research.
`per_page`	integer	—	Results per page (1–500). Default: 50.

bash

# Coverage gate before running a backtest
curl 'https://api.quantgist.com/v2/backtest/coverage?canonical_id=US_CPI_YOY' \
  -H 'X-API-Key: YOUR_API_KEY'

# First-print US CPI values as of 2024-06-15 (before any later revisions)
curl 'https://api.quantgist.com/v2/backtest?canonical_id=US_CPI_YOY&as_of=2024-06-15' \
  -H 'X-API-Key: YOUR_API_KEY'

# Common US macro series
curl 'https://api.quantgist.com/v2/backtest?canonical_id=US_NFP&from_date=2022-01-01' \
  -H 'X-API-Key: YOUR_API_KEY'
curl 'https://api.quantgist.com/v2/backtest?canonical_id=US_FOMC_RATE_DECISION&from_date=2022-01-01' \
  -H 'X-API-Key: YOUR_API_KEY'
curl 'https://api.quantgist.com/v2/backtest?canonical_id=US_GDP_QOQ_ADVANCE&from_date=2022-01-01' \
  -H 'X-API-Key: YOUR_API_KEY'
curl 'https://api.quantgist.com/v2/backtest?canonical_id=US_PCE_YOY&from_date=2022-01-01' \
  -H 'X-API-Key: YOUR_API_KEY'
curl 'https://api.quantgist.com/v2/backtest?canonical_id=US_CORE_PCE_YOY&from_date=2022-01-01' \
  -H 'X-API-Key: YOUR_API_KEY'

json

{
  "data": [
    {
      "id": "...",
      "canonical_id": "US_CPI_YOY",
      "title": "US Consumer Price Index (Year-over-Year)",
      "release_time": "2024-05-15T12:30:00Z",
      "actual": "3.4",
      "forecast": "3.4",
      "previous": "3.5",
      "verification_status": "verified",
      "source": "bls",
      "source_url": "https://www.bls.gov/news.release/cpi.htm"
    }
  ],
  "total": 12,
  "backtest_mode": true
}

Note:The response always carries backtest_mode: true, contract_version, excluded_missing_vintage_count, and the X-Backtest-Mode: true header. Without as_of, rows use first-print vintages; with it, rows use only values published on or before the cutoff.

Note:Coverage is growing. Check GET /v2/backtest/coverage to see which canonical IDs have sufficient verified history for your date range. Forecast and previous fields are reported separately from actual-value readiness; surprise backtests require enough forecast coverage and should inspect coverage before use.

MCP Server: AI Agent Quick-Start

The QuantGist MCP server exposes 11 tools (macro events, earnings, market overview) to Claude Desktop, Claude Code, and any MCP-compatible agent. Full docs at /docs/mcp.

● Claude Desktop

Add to claude_desktop_config.json:

json

{
  "mcpServers": {
    "quantgist": {
      "command": "quantgist-mcp",
      "env": {
        "QUANTGIST_API_KEY": "qg_live_..."
      }
    }
  }
}

● Claude Code (CLI)

Install then register:

bash

pip install git+https://github.com/\
  QuantGist-Technologies/QuantGist_MCP.git

claude mcp add quantgist \
  -e QUANTGIST_API_KEY=qg_live_... \
  -- quantgist-mcp

Tip:Full tool reference, parameter schemas, and agent workflow examples at /docs/mcp. Get a free API key at /signup.

Recipes

Common patterns: copy, paste, and adapt. Each snippet is a self-contained curl command you can run immediately.

Note:All /v1/macro/* endpoints return the same event shape as /v1/events.

Get next NFP release

Fetch the next scheduled Non-Farm Payrolls release using the macro shortcut layer.

bash

# Get the next scheduled Non-Farm Payrolls release
curl 'https://api.quantgist.com/v1/macro/upcoming?event=NFP' \
  -H 'X-API-Key: YOUR_KEY'

# Or use the calendar endpoint for NFP + CPI in the next 30 days
curl 'https://api.quantgist.com/v1/macro/calendar?events=NFP,CPI&days=30' \
  -H 'X-API-Key: YOUR_KEY'

Get latest CPI value

Retrieve the most recently released US CPI figure, including actual, forecast, and previous values.

bash

# Get the most recently released US CPI figure
curl 'https://api.quantgist.com/v1/macro/latest?event=CPI' \
  -H 'X-API-Key: YOUR_KEY'

# Response includes: actual, forecast, previous, release_time, is_released

Get high-impact USD events this week

Query high-impact USD macro events for the next 7 days, optionally excluding earnings.

bash

# High-impact USD macro events in the next 7 days
curl 'https://api.quantgist.com/v1/calendar?currency=USD&impact=high&days=7' \
  -H 'X-API-Key: YOUR_KEY'

# With earnings excluded (default behaviour, pass include_earnings=true to opt in)
curl 'https://api.quantgist.com/v1/calendar?currency=USD&impact=high&days=7&include_earnings=false' \
  -H 'X-API-Key: YOUR_KEY'

Export historical events to NDJSON

Stream all economic releases for a date range as NDJSON, each line is a standalone JSON object, ready to pipe into jq, pandas, or any streaming processor.

bash

# Stream all economic releases for January 2024 as NDJSON
# Each line is a standalone JSON object, pipe to jq, pandas, etc.
curl 'https://api.quantgist.com/v1/events/historical?from_date=2024-01-01&to_date=2024-01-31&event_type=economic_release' \
  -H 'X-API-Key: YOUR_KEY' \
  | jq -c 'select(.is_released == true)'

# Python: parse NDJSON line by line
# import httpx, json
# with httpx.stream("GET", url, headers=headers) as r:
#     for line in r.iter_lines():
#         event = json.loads(line)

Postman & OpenAPI

The API exposes a live OpenAPI 3.1 spec at https://api.quantgist.com/openapi.json. Import it directly into Postman, Insomnia, Bruno, or any code-generation tool to scaffold typed clients.

Interactive Swagger UI is available at api.quantgist.com/docs and ReDoc at api.quantgist.com/redoc.

Note:A pre-built Postman collection is on the roadmap. In the meantime, importing the OpenAPI spec gives you the same coverage with one click.

PreviousQuickstartGet your first API call working in 60 seconds Next Python SDKInstall and use the official Python client

Ready to start building?

Get your free API key in seconds. No credit card required.

Get API Key

API Reference

API Reference v1

API Reference

Integrate real-time economic data into your trading systems in minutes.

Base URLhttps://api.quantgist.com/v1

AuthX-API-Keyheader

Get API Key

Introduction

New here? Grab a key, then make your first request in under five minutes.

Step 1Get an API keyGenerate live or test keys from your dashboard. Step 25-minute QuickstartFetch your first events response with curl or an SDK.

API Keys

Manage your keys at /dashboard/keys. Each key shows its prefix (the first 12 characters) so you can identify it without exposing the full value.

Sending the header

curl https://api.quantgist.com/v1/events \
  -H "X-API-Key: qg_live_your_key_here"

Quickstart

Five minutes from zero to your first response.

Sign up for a QuantGist account (no card required for the free tier).
Generate an API key from /dashboard/keys — copy the full value the moment it is shown.
Make your first request:

curl "https://api.quantgist.com/v1/events?limit=5" \
  -H "X-API-Key: qg_live_your_key_here"

Install an SDK

Official client libraries handle pagination, retries, and typed responses.

pip install quantgist

Source: Python SDK · JavaScript SDK

Trader-friendly macro shortcuts

Skip the event search: use /v1/macro/* to fetch well-known releases by name. Supported aliases: NFP, CPI, PCE, FOMC, GDP, UNEMPLOYMENT, RETAIL_SALES, PPI, ISM, ECB, HICP.

bash

# Latest released NFP value
curl 'https://api.quantgist.com/v1/macro/latest?event=NFP' \
  -H 'X-API-Key: YOUR_KEY'

# Next scheduled CPI release
curl 'https://api.quantgist.com/v1/macro/upcoming?event=CPI' \
  -H 'X-API-Key: YOUR_KEY'

# Grouped calendar: CPI, NFP, and FOMC in the next 14 days
curl 'https://api.quantgist.com/v1/macro/calendar?events=CPI,NFP,FOMC&days=14' \
  -H 'X-API-Key: YOUR_KEY'

Note:Next: read about authentication or jump straight to the Events endpoint.

Authentication

All API requests must include your API key in the X-API-Key HTTP header. Generate and manage keys from your dashboard.

curl https://api.quantgist.com/v1/events \
  -H "X-API-Key: qg_live_your_key_here"

Authentication errors

Field	Type	Description
`401`	Unauthorized	No API key supplied, or the key format is invalid.
`403`	Forbidden	Valid key, but your plan does not include this endpoint.
`429`	Too Many Requests	Daily or per-minute rate limit exceeded. Check X-RateLimit-* response headers.

Events

Returns a paginated list of economic events matching your filters.

ENDPOINT|GET/v1/events#

Note:Free-plan responses carry a 15-minute delay. Upgrade to Starter or above for near real-time data.

Query parameters

Param	Type	Req	Description
`symbol`	string	—	Filter by ticker symbol (e.g. EURUSD, SPX). Comma-separated for multiple.
`currency`	string	—	ISO 4217 currency code (e.g. USD, EUR).
`impact`	string	—	Event impact level: low \| medium \| high.
`event_type`	string	—	Type of event: earnings \| fomc \| cpi \| nfp \| gdp \| pmi \| other.
`from_date`	ISO 8601	—	Start of date range (inclusive). e.g. 2024-01-01T00:00:00Z.
`to_date`	ISO 8601	—	End of date range (inclusive).
`q`	string	—	Free-text search across event title and description.
`page`	integer	—	Page number, 1-indexed. Default: 1.
`page_size`	integer	—	Results per page (max 100). Default: 20.

Example response

json

{
  "data": [
    {
      "id": "evt_01HX9M3K4R2BGCZ8JQNVP7YW5E",
      "event_type": "nfp",
      "title": "US Non-Farm Payrolls (Mar 2024)",
      "currency": "USD",
      "impact": "high",
      "release_time": "2024-04-05T12:30:00Z",
      "actual": 303000,
      "forecast": 214000,
      "previous": 270000,
      "surprise_pct": 41.6,
      "sentiment_score": 0.82
    }
  ],
  "meta": {
    "page": 1,
    "page_size": 20,
    "total": 1842,
    "has_more": true
  }
}

Single Event

Fetch the full event object including all fields and historical revisions.

ENDPOINT|GET/v1/events/{event_id}#

Response schema

Field	Type	Description
`id`	string	Unique event identifier (ULID format).
`event_type`	string	Category: earnings \| fomc \| cpi \| nfp \| gdp \| pmi \| other.
`title`	string	Human-readable event title.
`currency`	string	Primary currency affected (ISO 4217).
`symbol`	string \| null	Primary ticker symbol if applicable.
`impact`	string	Assessed market impact: low \| medium \| high.
`release_time`	ISO 8601	Scheduled or actual release timestamp (UTC).
`actual`	number \| null	Actual reported value.
`forecast`	number \| null	Consensus forecast prior to release.
`previous`	number \| null	Prior period value (may be revised).
`surprise_pct`	number \| null	Percentage surprise vs. forecast.
`sentiment_score`	number \| null	NLP-derived market sentiment −1 to +1. Pro+ only.
`impact_score`	number \| null	Deterministic 0–1 score combining impact level, event type, and keyword cues. Beta, may be null for some events.
`summary`	string \| null	One-line plain-text summary of the event. Beta, template-generated, may be null for some events.
`tags`	string[]	Semantic tags for topic classification.

Historical Data

Bulk-download historical events. Supports NDJSON format for streaming large datasets efficiently.

ENDPOINT|GET/v1/events/historical#

Warning:NDJSON bulk download requires an Enterprise plan. Lower plans are limited to standard paginated JSON.

Query parameters

Param	Type	Req	Description
`from_date`	ISO 8601	yes	Start of range.
`to_date`	ISO 8601	yes	End of range (max 365-day window).
`symbol`	string	—	Ticker symbol filter (comma-separated).
`currency`	string	—	ISO 4217 currency code.
`format`	string	—	Response format: json (default) \| ndjson.
`page`	integer	—	Page number for JSON format. Default: 1.

bash

curl "https://api.quantgist.com/v1/events/historical?from_date=2024-01-01&to_date=2024-03-31&format=ndjson" \
  -H "X-API-Key: qg_live_your_key_here" \
  --output events.ndjson

Calendar

Returns today's economic calendar. Defaults to UTC date if no date is supplied.

ENDPOINT|GET/v1/calendar#

Param	Type	Req	Description
`date`	YYYY-MM-DD	—	Calendar date. Defaults to today (UTC).
`currency`	string	—	Filter to one or more currencies.
`impact`	string	—	Minimum impact level: low \| medium \| high.
`include_actual`	boolean	—	Include actual values for past events. Default: true.

Example response

json

{
  "date": "2024-04-23",
  "events": [
    {
      "id": "evt_01HX9...",
      "title": "Fed Interest Rate Decision",
      "currency": "USD",
      "impact": "high",
      "release_time": "2024-04-23T18:00:00Z",
      "forecast": 5.5,
      "actual": null,
      "previous": 5.5
    }
  ],
  "count": 14
}

Calendar Range

Returns the economic calendar for a multi-day range. Both date_from and date_to are required.

ENDPOINT|GET/v1/calendar/range#

Param	Type	Req	Description
`date_from`	YYYY-MM-DD	yes	Start date of the range (inclusive).
`date_to`	YYYY-MM-DD	yes	End date of the range (inclusive, max +30 days).
`currency`	string	—	Currency filter.
`impact`	string	—	Minimum impact: low \| medium \| high.

Macro Shortcuts

Trader-friendly convenience layer on top of /v1/events and /v1/calendar. Reference well-known macro releases by alias (e.g. NFP, CPI) without knowing the exact event title or ID.

ENDPOINT|GET/v1/macro/events#

List all supported macro aliases and their canonical event types.

ENDPOINT|GET/v1/macro/latest#

Most recent released row for the given alias. Query param: event (e.g. NFP).

ENDPOINT|GET/v1/macro/upcoming#

Next scheduled release for the given alias. Query param: event (e.g. CPI).

ENDPOINT|GET/v1/macro/calendar#

Grouped upcoming releases for multiple aliases. Query params: events (comma-separated), days (default 14).

Supported aliases: NFP, CPI, PCE, FOMC, GDP, UNEMPLOYMENT, RETAIL_SALES, PPI, ISM, ECB, HICP.

bash

# Latest released NFP
curl 'https://api.quantgist.com/v1/macro/latest?event=NFP' \
  -H 'X-API-Key: YOUR_KEY'

# Next CPI release
curl 'https://api.quantgist.com/v1/macro/upcoming?event=CPI' \
  -H 'X-API-Key: YOUR_KEY'

# CPI + NFP + FOMC calendar for the next 14 days
curl 'https://api.quantgist.com/v1/macro/calendar?events=CPI,NFP,FOMC&days=14' \
  -H 'X-API-Key: YOUR_KEY'

# All supported aliases
curl 'https://api.quantgist.com/v1/macro/events' \
  -H 'X-API-Key: YOUR_KEY'

Backtesting with canonical events

bash

# Canonical CPI history, strict v2 backtest contract
GET /v2/backtest?canonical_id=US_CPI_YOY&from_date=2020-01-01&to_date=2026-01-01

# Readiness gate before allocating research compute
GET /v2/backtest/coverage?canonical_id=US_CPI_YOY

# Raw export only; do not use this as the macro backtesting contract
GET /v1/events/historical?from_date=2025-01-01&to_date=2025-01-31&format=ndjson

News Live

Choosing the right news surface

Sample queries

bash

# Raw headlines about Iran/war: readable feed, single-source rows
GET /v1/news?q=iran%20war&per_page=10

Returns headlines with summary, summary_source, topic_matches, and a per-headline impact_score capped low for single-source rows.

bash

# Clustered Iran-conflict trade intelligence above an alert threshold
GET /v1/news/radar?topic=iran-war&min_impact=0.5

Returns clustered events with impact_score, affected_assets, why_it_matters, and a lifecycle status.

bash

# Oil-supply disruption clusters (OPEC, pipelines, refineries, Hormuz)
GET /v1/news/radar?topic=oil-supply&min_impact=0.5

Returns supply-shock clusters — matches require both an energy-context term and a disruption term (see Topic evidence gate below), so a generic “explosion” headline will not score here.

bash

# Earnings history for a ticker
GET /v1/earnings/AAPL?limit=12

Returns up to 12 most recent earnings rows with EPS actual/estimate/surprise, fiscal period, and per-field provenance in field_sources.

Topic evidence gate

News summary semantics

Every row on /v1/news exposes a summary_source field so you can trust or discount the summary appropriately:

Field	Type	Description
`source`	string	Summary came from the publisher (Alpha Vantage news, vendor RSS body). Faithfully reflects the article.
`rule_template`	string	Deterministic 1-sentence fallback we generate from title + matched topic + affected assets when the publisher provided no summary. No facts beyond the headline.
`none`	string	No usable title or template input, summary is null.

News Radar topic packs — quick reference

Topic slug	Description
`iran-war`	Iran military conflict and Hormuz shipping risk
`oil-supply`	OPEC+ cuts, pipeline outages, supply disruptions
`sanctions`	New or lifted economic sanctions
`central-bank-unscheduled`	Emergency / unscheduled central bank rate moves
`trump-posts`	Trump social-media policy announcements
`middle-east-risk`	Broader Middle East geopolitical escalation
`cyberattack`	Major infrastructure or financial-sector cyber incidents
`ceasefire`	Ceasefire announcements and de-escalation signals
`opec`	OPEC/OPEC+ production decisions and compliance reports

bash

# Unscheduled geopolitical risk: Iran conflict clusters, high-impact only
GET /v1/news/radar?topic=iran-war&min_impact=0.6&limit=10

# Emergency central-bank moves (surprise rate cuts/hikes)
GET /v1/news/radar?topic=central-bank-unscheduled&limit=5

# Raw keyword search across all headlines
GET /v1/news?q=OPEC&currency=USD&impact=high

Retrieves structured financial news headlines aggregated from Bloomberg, WSJ, CNBC, NYT, and Yahoo Finance. Headlines are ingested every 20 minutes and tagged by currency, symbol, and impact.

ENDPOINT|GET/v1/news#

Param	Type	Req	Description
`source`	string	—	Filter by news source identifier.
`currency`	string	—	Currency mentioned in the article.
`symbol`	string	—	Ticker symbol referenced.
`impact`	string	—	Assessed impact: low \| medium \| high.
`q`	string	—	Full-text search across title and body.
`page`	integer	—	Page number. Default: 1.

json

{
  "data": [
    {
      "id": "...",
      "event_type": "news_headline",
      "source": "rss_news",
      "title": "Fed Holds Rates Steady as Officials Weigh Inflation Path",
      "summary": "Federal Reserve officials held interest rates steady and signalled they remain cautious about cutting borrowing costs.",
      "published_at": "2026-05-25T14:30:00Z",
      "source_url": "https://www.wsj.com/articles/fed-holds-rates-steady-...",
      "currency": "USD",
      "symbols": ["SPY", "TLT"],
      "sentiment_score": -0.12,
      "sentiment_label": "bearish",
      "impact": "high"
    }
  ],
  "total": 200,
  "page": 1,
  "per_page": 5
}

News Radar Live

ENDPOINT|GET/v1/news/radar#

Param	Type	Req	Description
`topic`	string	—	Topic slug (e.g. iran-war). See /v1/news/topics.
`symbols`	string	—	Comma-separated tickers; match any (e.g. USO,GLD,SPY).
`min_impact`	number	—	Minimum impact_score in [0, 1]. Default 0.0.
`event_type`	string	—	geopolitical_risk \| supply_shock \| policy_shock \| cyber \| de_escalation \| supply_policy.
`status`	string	—	developing \| breaking \| fading \| resolved.
`lookback_hours`	integer	—	Window over latest_seen. Default 72, max 720.
`limit`	integer	—	Max clusters returned. Default 50, max 200.

json

{
  "items": [
    {
      "id": "9c3e1a4f-...",
      "topic": "iran-war",
      "headline": "Iran strikes oil facility in coordinated drone attack",
      "why_it_matters": "Active Iran conflict threatens the Strait of Hormuz, the chokepoint for ~20% of global seaborne oil...",
      "impact_score": 0.82,
      "confidence": 0.76,
      "affected_assets": ["CL", "USO", "XLE", "GLD", "XAUUSD"],
      "affected_assets_source": "llm",
      "event_type": "geopolitical_risk",
      "status": "breaking",
      "source_count": 8,
      "first_seen": "2026-05-27T11:14:00Z",
      "latest_seen": "2026-05-27T14:02:00Z"
    }
  ],
  "total": 1,
  "min_impact": 0.65,
  "lookback_hours": 72
}

News Topics Live

ENDPOINT|GET/v1/news/topics#

json

{
  "items": [
    {
      "slug": "iran-war",
      "display_name": "Iran War Risk",
      "description": "Military conflict, sanctions tightening, or escalation rhetoric involving Iran...",
      "event_type": "geopolitical_risk",
      "affected_assets": ["CL", "USO", "XLE", "GLD", "XAUUSD", "SPY", "DAL", "LMT", "..."],
      "affected_asset_classes": {
        "oil": ["CL", "USO", "XLE", "BNO", "XOP"],
        "safe_haven": ["GLD", "XAUUSD", "USDJPY", "USDCHF", "TLT"],
        "defense": ["LMT", "RTX", "NOC", "BA", "GD", "ITA"]
      },
      "related_topics": ["middle-east-risk", "oil-supply"]
    }
  ],
  "total": 9
}

News Watchlists Starter+

ENDPOINT|GET/v1/news/watchlists#

json

{
  "items": [
    {
      "id": "e2a1f3b4-0000-0000-0000-000000000001",
      "topic_slug": "iran-war",
      "min_impact": 0.5,
      "created_at": "2026-05-28T10:00:00Z"
    }
  ],
  "total": 1
}

ENDPOINT|POST/v1/news/watchlists#

Subscribe to a topic pack. Returns 409 if already subscribed.

Param	Type	Req	Description
`topic_slug`	string	yes	Topic pack slug (e.g. iran-war). See /v1/news/topics.
`min_impact`	number	—	Min impact_score [0, 1] to trigger an alert. Default 0.5.

ENDPOINT|DELETE/v1/news/watchlists/{topic_slug}#

Unsubscribe from a topic pack. Cascades to all associated alerts. Returns 204 No Content.

Param	Type	Req	Description
`topic_slug`	string	yes	The topic pack slug to unsubscribe from (path parameter).

News Alerts Starter+

Alerts are created automatically when a new cluster crosses your watchlist min_impact threshold. Fetch unread alerts, acknowledge individual ones, or clear all in one shot.

ENDPOINT|GET/v1/news/alerts#

Param	Type	Req	Description
`unread_only`	boolean	—	Only return unread alerts (acked_at is null). Default true.
`limit`	integer	—	Max alerts to return (1–200). Default 50.

json

{
  "items": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "topic_slug": "iran-war",
      "acked_at": null,
      "created_at": "2026-05-28T11:00:00Z",
      "cluster": {
        "headline": "Iran drones target oil facility near Kharg Island",
        "impact_score": 0.85,
        "status": "breaking",
        "why_it_matters": "Escalation near Kharg Island threatens ~90% of Iran's oil export capacity...",
        "why_it_matters_source": "llm",
        "affected_assets": ["USO", "CL", "XLE", "GLD"],
        "affected_assets_source": "llm"
      }
    }
  ],
  "total": 3,
  "unread_only": true
}

ENDPOINT|POST/v1/news/alerts/{alert_id}/ack#

Mark a single alert as read. Returns the updated alert object with acked_at set.

Param	Type	Req	Description
`alert_id`	string	yes	Alert UUID (path parameter).

ENDPOINT|POST/v1/news/alerts/ack-all#

Mark all unread alerts as read. Returns a count of acknowledged alerts.

json

{ "acked": 5 }

Symbols

Reference data for all supported ticker symbols and currency pairs.

ENDPOINT|GET/v1/symbols#

Param	Type	Req	Description
`q`	string	—	Search by symbol or name.
`currency`	string	—	Filter by base currency.

json

{
  "data": [
    {
      "symbol": "EURUSD",
      "name": "Euro / US Dollar",
      "category": "forex",
      "base_currency": "EUR",
      "quote_currency": "USD",
      "exchange": "FX"
    }
  ],
  "total": 312
}

Earnings

Endpoints

ENDPOINT|GET/v1/earnings#

Paginated list of recent earnings events. Filter by ticker, date range, or beat/miss.

ENDPOINT|GET/v1/earnings/upcoming#

Earnings events scheduled in the next 30 days.

ENDPOINT|GET/v1/earnings/{ticker}#

Most recent earnings event for a specific ticker.

ENDPOINT|GET/v1/earnings/{ticker}/summary#

Aggregated beat/miss statistics for a ticker.

ENDPOINT|GET/v1/earnings/{ticker}/history#

Full historical earnings series for a ticker. Pro+ only.

ENDPOINT|GET/v1/earnings/surprises#

Top EPS and revenue surprises from the last 30 days.

ENDPOINT|GET/v1/earnings/movers#

Stocks with the largest post-earnings price moves.

ENDPOINT|GET/v1/earnings/calendar/week#

Earnings calendar for the current or a specified week.

ENDPOINT|GET/v1/earnings/calendar.ics#

iCalendar (.ics) feed, subscribe in Google Calendar / Outlook.

ENDPOINT|GET/v1/earnings/season/summary#

Aggregate beat rate, sector breakdown, and key stats for the active earnings season.

EarningsEventResponse schema

Field	Type	Description
`id`	string	Unique event identifier (ULID).
`ticker`	string	Equity ticker symbol (e.g. AAPL).
`company_name`	string	Issuing company name.
`report_date`	ISO 8601	Date of earnings release.
`fiscal_quarter`	string	Fiscal quarter reported (e.g. Q1 2025).
`eps_actual`	number \| null	Reported EPS.
`eps_estimate`	number \| null	Consensus EPS estimate.
`eps_surprise_pct`	number \| null	EPS surprise as a percentage.
`revenue_actual`	number \| null	Reported revenue (USD).
`revenue_estimate`	number \| null	Consensus revenue estimate (USD).
`sec_filing_url`	string \| null	Direct URL to the SEC EDGAR 8-K filing.
`sec_accession_number`	string \| null	SEC EDGAR accession number for the filing.
`sec_filed_at`	ISO 8601 \| null	Timestamp the 8-K was filed with the SEC.
`field_sources`	object	Per-field provenance map, indicates whether each field came from SEC EDGAR, yfinance, or another source.

Example response

json

{
  "id": "earn_01HX9M3K4R2BGCZ8JQNV",
  "ticker": "AAPL",
  "company_name": "Apple Inc.",
  "report_date": "2025-05-01",
  "fiscal_quarter": "Q2 2025",
  "eps_actual": 1.65,
  "eps_estimate": 1.61,
  "eps_surprise_pct": 2.48,
  "revenue_actual": 95370000000,
  "revenue_estimate": 94460000000,
  "sec_filing_url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000051/0000320193-25-000051-index.htm",
  "sec_accession_number": "0000320193-25-000051",
  "sec_filed_at": "2025-05-01T20:05:00Z",
  "field_sources": {
    "eps_actual": "sec_edgar",
    "revenue_actual": "sec_edgar",
    "eps_estimate": "yfinance"
  }
}

Market Overview

Endpoints

ENDPOINT|GET/v1/markets/overview#

All tracked groups (indexes, equities, commodities) in one response.

ENDPOINT|GET/v1/markets/indexes#

Cached daily snapshot of US index ETFs (SPY, QQQ, DIA).

ENDPOINT|GET/v1/markets/equities#

Cached daily snapshot of tracked large-cap equities.

ENDPOINT|GET/v1/markets/sectors#

Sector ETF performance, returns empty list until extended coverage is seeded.

ENDPOINT|GET/v1/markets/currencies#

FX rates, returns empty list until extended coverage is seeded.

ENDPOINT|GET/v1/markets/commodities#

Cached daily snapshot of commodity ETFs (GLD, USO).

ENDPOINT|GET/v1/markets/{symbol}#

Latest cached snapshot for any symbol in the DB.

Changelog

Returns a JSON array of API changes in reverse chronological order. Public, no authentication required.

ENDPOINT|GET/v1/changelog#

Tip:No X-API-Key header needed for this endpoint. Suitable for status pages and SDK auto-update checks.

bash

curl https://api.quantgist.com/v1/changelog

Example response

json

[
  {
    "version": "1.5.0",
    "date": "2025-05-01",
    "summary": "Earnings API: 10 new endpoints including SEC EDGAR provenance",
    "breaking": false
  },
  {
    "version": "1.4.0",
    "date": "2025-04-10",
    "summary": "Market Overview endpoints: cached quote snapshots via Alpha Vantage",
    "breaking": false
  }
]

Real-time WebSocket

Subscribe to a live event stream. The server sends a snapshot of recent events on connect, then pushes new events as they are published.

WSwss://api.quantgist.com/v1/stream

Tip:Authenticate via the ?api_key=qg_live_… query parameter. The X-API-Key header is not forwarded by browser WebSocket clients.

javascript

const ws = new WebSocket(
  "wss://api.quantgist.com/v1/stream?api_key=qg_live_your_key_here"
);

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: "subscribe",
    currencies: ["USD", "EUR"],
    impact: ["high"]
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === "snapshot") {
    console.log("Initial snapshot:", msg.events);
  } else if (msg.type === "event") {
    console.log("New event:", msg.data);
  }
};

Field	Type	Description
`type`	string	"snapshot" on connect, "event" for live updates, "ping" for keep-alive.
`events`	Event[]	Included in snapshot messages only.
`data`	Event	Single event object in live update messages.
`ts`	ISO 8601	Server-side timestamp of the message.

Intelligence: Surprises

Starter+

Recent economic releases ranked by surprise magnitude (how far actual values deviated from forecast). Positive scores beat expectations, negative scores missed.

ENDPOINT|GET/v1/intelligence/surprises#

Param	Type	Req	Description
`hours`	integer	—	Look-back window in hours (1–168). Default: 24.
`limit`	integer	—	Max number of results (1–100). Default: 20.
`currency`	string	—	Filter by ISO currency code (e.g. USD).
`min_impact`	string	—	Minimum impact level: low \| medium \| high.

bash

curl "https://api.quantgist.com/v1/intelligence/surprises?hours=24&min_impact=high" \
  -H "X-API-Key: qg_live_your_key_here"

Intelligence: Movers

Events ranked by expected market-impact potential, a composite of impact level, event category importance, and recent surprise magnitude.

ENDPOINT|GET/v1/intelligence/movers#

Param	Type	Req	Description
`hours`	integer	—	Look-back window in hours (1–168). Default: 24.
`limit`	integer	—	Max number of results (1–100). Default: 20.
`currency`	string	—	ISO currency code filter.
`min_score`	number	—	Drop events below this composite mover score.

bash

curl "https://api.quantgist.com/v1/intelligence/movers?currency=USD&limit=10" \
  -H "X-API-Key: qg_live_your_key_here"

Sentiment Summary

Starter+

Aggregate sentiment statistics grouped by a chosen dimension (currency, country, event_type, or sector).

ENDPOINT|GET/v1/sentiment/summary#

Param	Type	Req	Description
`group_by`	string	—	Dimension: currency \| country \| event_type \| sector.
`hours`	integer	—	Look-back window in hours. Default: 24.
`min_impact`	string	—	Minimum event impact: low \| medium \| high.

bash

curl "https://api.quantgist.com/v1/sentiment/summary?group_by=currency&hours=48" \
  -H "X-API-Key: qg_live_your_key_here"

Sentiment: Events

Paginated list of events filtered and sorted by sentiment score.

ENDPOINT|GET/v1/sentiment/events#

Param	Type	Req	Description
`label`	string	—	Sentiment label: positive \| neutral \| negative.
`min_score`	number	—	Minimum sentiment score (-1 to 1).
`max_score`	number	—	Maximum sentiment score (-1 to 1).
`currency`	string	—	ISO currency code filter.
`from_date`	ISO 8601	—	Start of date range.
`to_date`	ISO 8601	—	End of date range.
`page`	integer	—	Page number. Default: 1.
`page_size`	integer	—	Results per page (max 100). Default: 20.

bash

curl "https://api.quantgist.com/v1/sentiment/events?label=negative&min_score=-1&max_score=-0.4" \
  -H "X-API-Key: qg_live_your_key_here"

Data Export

Stream a compressed bulk export of events for a specified date range.

ENDPOINT|GET/v1/data/export#

Warning:Bulk export is available on Pro and above. Supports NDJSON and CSV formats.

Param	Type	Req	Description
`from_date`	ISO 8601	yes	Start of range (inclusive).
`to_date`	ISO 8601	yes	End of range (inclusive).
`format`	string	—	ndjson (default) \| csv.
`currency`	string	—	ISO currency code filter.

bash

curl "https://api.quantgist.com/v1/data/export?from_date=2024-01-01&to_date=2024-03-31&format=ndjson" \
  -H "X-API-Key: qg_live_your_key_here" \
  --output events.ndjson

Data Packs

Pre-built historical bundles. The catalogue is public; downloads require Pro+.

ENDPOINT|GET/v1/data/packs#

List all available data packs. No authentication required.

ENDPOINT|GET/v1/data/packs/{pack_id}/download#

Stream a pack as NDJSON. Pro+ required.

Organizations

Multi-seat workspaces with shared usage quotas. Create orgs, manage members, and invite teammates.

ENDPOINT|POST/v1/organizations#

Create a new organization.

ENDPOINT|GET/v1/organizations#

List organizations the authenticated user belongs to.

ENDPOINT|GET/v1/organizations/{org_id}#

Fetch a single organization.

Organization Members

ENDPOINT|POST/v1/organizations/{org_id}/members#

ENDPOINT|GET/v1/organizations/{org_id}/members#

ENDPOINT|DELETE/v1/organizations/{org_id}/members/{user_id}#

ENDPOINT|GET/v1/organizations/{org_id}/usage#

Organization Invites

ENDPOINT|POST/v1/organizations/{org_id}/invites#

ENDPOINT|GET/v1/organizations/{org_id}/invites#

ENDPOINT|POST/v1/organizations/invites/accept#

Webhooks

Pro+

ENDPOINT|POST/v1/webhooks#

ENDPOINT|GET/v1/webhooks#

ENDPOINT|PUT/v1/webhooks/{endpoint_id}#

ENDPOINT|DELETE/v1/webhooks/{endpoint_id}#

ENDPOINT|POST/v1/webhooks/{endpoint_id}/test#

ENDPOINT|GET/v1/webhooks/branding#

ENDPOINT|PUT/v1/webhooks/branding#

Notifications

ENDPOINT|POST/v1/notifications/channels#

ENDPOINT|GET/v1/notifications/channels#

ENDPOINT|GET/v1/notifications/channels/{channel_id}#

ENDPOINT|PUT/v1/notifications/channels/{channel_id}#

ENDPOINT|DELETE/v1/notifications/channels/{channel_id}#

Send Test Notification

Dispatch a synthetic test message to a channel to verify it is correctly configured.

ENDPOINT|POST/v1/notifications/channels/{channel_id}/test#

SLA Status

Public

Returns the last 30 days of pre-computed SLA metrics (uptime, ingestion latency, freshness). No authentication required.

ENDPOINT|GET/v1/sla/status#

bash

curl https://api.quantgist.com/v1/sla/status

Usage Stats

Returns your current API usage statistics and plan limits for today.

ENDPOINT|GET/v1/usage#

json

{
  "plan": "pro",
  "period": "2024-04-23",
  "requests": {
    "today": 1204,
    "limit": 50000,
    "remaining": 48796,
    "reset_at": "2024-04-24T00:00:00Z"
  },
  "rate_limit": {
    "per_minute": 120,
    "remaining_this_minute": 117
  }
}

Auth Endpoints

Manage user accounts and API keys at https://api.quantgist.com/auth.

ENDPOINT|POST/auth/register#

Create a new account. Returns a JWT access token and initial API key.

Param	Type	Req	Description
`email`	string	yes	User email address.
`password`	string	yes	Min 8 characters.
`name`	string	—	Display name.

ENDPOINT|POST/auth/login#

Exchange credentials for a JWT access token.

Param	Type	Req	Description
`email`	string	yes	Registered email address.
`password`	string	yes	Account password.

ENDPOINT|GET/auth/keys#

List all API keys for the authenticated user (key values are masked).

ENDPOINT|DELETE/auth/keys/{id}#

Permanently revoke an API key. This action cannot be undone.

Billing

Manage subscriptions via Stripe. Requires a JWT Bearer token.

ENDPOINT|POST/billing/checkout#

Start a Stripe Checkout session to upgrade your plan. Returns a redirect URL.

Param	Type	Req	Description
`plan`	string	yes	Target plan: starter \| pro \| team.
`annual`	boolean	—	Annual billing (2 months free). Default: false.

ENDPOINT|POST/billing/portal#

Open the Stripe Customer Portal to manage or cancel your subscription.

ENDPOINT|GET/billing/subscription#

Return the authenticated user's current plan and billing status.

Google OAuth

Sign in or sign up using a Google account. The browser is redirected to Google's consent screen, and the callback exchanges the code for a session and initial API key.

ENDPOINT|GET/v1/auth/google#

Redirect the browser to Google's OAuth 2.0 consent screen.

ENDPOINT|GET/v1/auth/google/callback#

Exchange the authorization code for a user record. Redirects to /auth/callback?key=&token=&new_user=.

Error Codes

All error responses follow a consistent JSON structure:

json

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "You have exceeded your daily request quota.",
    "status": 429,
    "docs": "https://quantgist.com/docs#error-codes"
  }
}

Code	Status	Meaning
`400`	Bad Request	The request was malformed or a required parameter is missing.
`401`	Unauthorized	No API key provided, or the key is invalid / expired.
`403`	Forbidden	Your plan does not include this endpoint or feature.
`404`	Not Found	The requested resource does not exist.
`422`	Unprocessable Entity	Validation failed. Check the errors array for field-level details.
`429`	Too Many Requests	Rate limit or daily quota exceeded. Retry after X-RateLimit-Reset.
`503`	Service Unavailable	Temporary maintenance. Check status.quantgist.com for updates.

Rate Limits

Field	Type	Description
`X-RateLimit-Limit`	integer	Maximum requests allowed in the current window.
`X-RateLimit-Remaining`	integer	Requests remaining before the next reset.
`X-RateLimit-Reset`	unix timestamp	When the current window resets (seconds since epoch).

Plan Limits

Each plan gates feature access and quota. Calls to endpoints outside your plan return 403 Forbidden; calls beyond your daily quota return 429 Too Many Requests.

Field	Type	Description
`Free`	100 req/day	15-minute delayed data. 1-year history. Events, calendar, symbols.
`Starter`	5,000 req/day	Near real-time data. 3-year history. Adds intelligence and sentiment.
`Pro`	50,000 req/day	Real-time. 10-year history. Adds webhooks, bulk NDJSON export, and per-ticker earnings history.
`Team`	250,000 req/month	Real-time. 730-day history. Unlimited watchlists, up to 10 WS connections.
`Enterprise`	unlimited	Real-time. Unlimited history. Custom SLA, dedicated support.

Tip:Compare plans and upgrade from /pricing or directly inside the dashboard billing page.

v2 Backtesting Mode

Field	Type	Description
`released_only`	bool	Exclude events with release_time in the future (calendar rows you cannot trade on yet).
`actual_required`	bool	Exclude events where actual is null (awaiting official figures).
`official_only`	bool	Restrict to official-source adapters (BLS, BEA, FRED, ECB, ONS). Excludes ForexFactory / Investing aggregators.
`first_print_only`	bool	Return the first-published value for each event, not the latest revision. Prevents look-ahead bias from later revisions.

ENDPOINT|GET/v2/backtest#

Param	Type	Req	Description
`canonical_id`	string	—	Canonical event ID (e.g. US_CPI_YOY, US_NFP).
`currency`	string	—	ISO 4217 currency filter.
`country`	string	—	ISO 3166-1 alpha-2 country filter.
`impact`	string	—	high \| medium \| low
`from_date`	ISO 8601	—	Start of date range. Defaults to 2 years ago.
`to_date`	ISO 8601	—	End of date range.
`as_of`	ISO 8601	—	Return the value as it was known on this date. Enables point-in-time queries.
`strict`	boolean	—	Default true. Fails closed when the requested canonical ID is not backtest-grade. Set false only for exploratory research.
`per_page`	integer	—	Results per page (1–500). Default: 50.

bash

# Coverage gate before running a backtest
curl 'https://api.quantgist.com/v2/backtest/coverage?canonical_id=US_CPI_YOY' \
  -H 'X-API-Key: YOUR_API_KEY'

# First-print US CPI values as of 2024-06-15 (before any later revisions)
curl 'https://api.quantgist.com/v2/backtest?canonical_id=US_CPI_YOY&as_of=2024-06-15' \
  -H 'X-API-Key: YOUR_API_KEY'

# Common US macro series
curl 'https://api.quantgist.com/v2/backtest?canonical_id=US_NFP&from_date=2022-01-01' \
  -H 'X-API-Key: YOUR_API_KEY'
curl 'https://api.quantgist.com/v2/backtest?canonical_id=US_FOMC_RATE_DECISION&from_date=2022-01-01' \
  -H 'X-API-Key: YOUR_API_KEY'
curl 'https://api.quantgist.com/v2/backtest?canonical_id=US_GDP_QOQ_ADVANCE&from_date=2022-01-01' \
  -H 'X-API-Key: YOUR_API_KEY'
curl 'https://api.quantgist.com/v2/backtest?canonical_id=US_PCE_YOY&from_date=2022-01-01' \
  -H 'X-API-Key: YOUR_API_KEY'
curl 'https://api.quantgist.com/v2/backtest?canonical_id=US_CORE_PCE_YOY&from_date=2022-01-01' \
  -H 'X-API-Key: YOUR_API_KEY'

json

{
  "data": [
    {
      "id": "...",
      "canonical_id": "US_CPI_YOY",
      "title": "US Consumer Price Index (Year-over-Year)",
      "release_time": "2024-05-15T12:30:00Z",
      "actual": "3.4",
      "forecast": "3.4",
      "previous": "3.5",
      "verification_status": "verified",
      "source": "bls",
      "source_url": "https://www.bls.gov/news.release/cpi.htm"
    }
  ],
  "total": 12,
  "backtest_mode": true
}

MCP Server: AI Agent Quick-Start

The QuantGist MCP server exposes 11 tools (macro events, earnings, market overview) to Claude Desktop, Claude Code, and any MCP-compatible agent. Full docs at /docs/mcp.

● Claude Desktop

Add to claude_desktop_config.json:

json

{
  "mcpServers": {
    "quantgist": {
      "command": "quantgist-mcp",
      "env": {
        "QUANTGIST_API_KEY": "qg_live_..."
      }
    }
  }
}

● Claude Code (CLI)

Install then register:

bash

pip install git+https://github.com/\
  QuantGist-Technologies/QuantGist_MCP.git

claude mcp add quantgist \
  -e QUANTGIST_API_KEY=qg_live_... \
  -- quantgist-mcp

Tip:Full tool reference, parameter schemas, and agent workflow examples at /docs/mcp. Get a free API key at /signup.

Recipes

Common patterns: copy, paste, and adapt. Each snippet is a self-contained curl command you can run immediately.

Note:All /v1/macro/* endpoints return the same event shape as /v1/events.

Get next NFP release

Fetch the next scheduled Non-Farm Payrolls release using the macro shortcut layer.

bash

# Get the next scheduled Non-Farm Payrolls release
curl 'https://api.quantgist.com/v1/macro/upcoming?event=NFP' \
  -H 'X-API-Key: YOUR_KEY'

# Or use the calendar endpoint for NFP + CPI in the next 30 days
curl 'https://api.quantgist.com/v1/macro/calendar?events=NFP,CPI&days=30' \
  -H 'X-API-Key: YOUR_KEY'

Get latest CPI value

Retrieve the most recently released US CPI figure, including actual, forecast, and previous values.

bash

# Get the most recently released US CPI figure
curl 'https://api.quantgist.com/v1/macro/latest?event=CPI' \
  -H 'X-API-Key: YOUR_KEY'

# Response includes: actual, forecast, previous, release_time, is_released

Get high-impact USD events this week

Query high-impact USD macro events for the next 7 days, optionally excluding earnings.

bash

# High-impact USD macro events in the next 7 days
curl 'https://api.quantgist.com/v1/calendar?currency=USD&impact=high&days=7' \
  -H 'X-API-Key: YOUR_KEY'

# With earnings excluded (default behaviour, pass include_earnings=true to opt in)
curl 'https://api.quantgist.com/v1/calendar?currency=USD&impact=high&days=7&include_earnings=false' \
  -H 'X-API-Key: YOUR_KEY'

Export historical events to NDJSON

Stream all economic releases for a date range as NDJSON, each line is a standalone JSON object, ready to pipe into jq, pandas, or any streaming processor.

bash

# Stream all economic releases for January 2024 as NDJSON
# Each line is a standalone JSON object, pipe to jq, pandas, etc.
curl 'https://api.quantgist.com/v1/events/historical?from_date=2024-01-01&to_date=2024-01-31&event_type=economic_release' \
  -H 'X-API-Key: YOUR_KEY' \
  | jq -c 'select(.is_released == true)'

# Python: parse NDJSON line by line
# import httpx, json
# with httpx.stream("GET", url, headers=headers) as r:
#     for line in r.iter_lines():
#         event = json.loads(line)

Postman & OpenAPI

The API exposes a live OpenAPI 3.1 spec at https://api.quantgist.com/openapi.json. Import it directly into Postman, Insomnia, Bruno, or any code-generation tool to scaffold typed clients.

Interactive Swagger UI is available at api.quantgist.com/docs and ReDoc at api.quantgist.com/redoc.

Note:A pre-built Postman collection is on the roadmap. In the meantime, importing the OpenAPI spec gives you the same coverage with one click.

PreviousQuickstartGet your first API call working in 60 seconds Next Python SDKInstall and use the official Python client

Ready to start building?

Get your free API key in seconds. No credit card required.

Get API Key