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

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.
`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 is available on Pro and above. Free and Starter plans return standard JSON only, capped at 1,000 rows.

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.

News

Retrieves structured, market-moving news headlines with sentiment metadata.

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.

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
}

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.

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.

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.

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

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

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.
`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 is available on Pro and above. Free and Starter plans return standard JSON only, capped at 1,000 rows.

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.

News

Retrieves structured, market-moving news headlines with sentiment metadata.

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.

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
}

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.

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.

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.

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