Data Mode

Premium

The mode parameter allows you to control how an API request is fulfilled, including data freshness guarantees and credit usage. The mode parameter determines the response behavior used to fulfill each request.

Our API supports three modes: live, cached, and delayed. These options balance immediacy, availability, and cost efficiency. Below is a detailed overview of each mode, including examples and recommended use-cases.

Premium Parameter

This parameter is available only on paid plans. Free and trial plans cannot change the data mode and will always receive delayed data.

Live Mode

The live mode returns real-time data, providing the most current market information available. This mode is intended for time-sensitive use cases that require up-to-the-second pricing.

Pricing for Live Mode

• Quotes: 1 credit per symbol included in the response that has quote data (bid/ask/mid/last).
• Candles: 1 credit per 1,000 candles included in the response.
• Bulk Candles: 1 credit per symbol* included in the response.
• Other Endpoints: 1 credit per response.

Requesting Live Data

To request real-time data, append mode=live to your API call or omit the parameter entirely. If the mode parameter is not specified, live mode is used by default for paid accounts.

GET https://api.marketdata.app/v1/options/chain/SPY/?mode=live
GET https://api.marketdata.app/v1/options/chain/SPY/

Both requests are valid and return the most recent data available for the specified symbol.

Cached Mode

The cached mode returns recently stored data that may be a few seconds to several minutes old. This mode is designed to reduce credit usage when retrieving large amounts of quote data.

Data freshness is not guaranteed. Symbols with higher usage across Market Data customers tend to be refreshed more frequently.

Pricing for Cached Mode

• Quotes: 1 credit per request, regardless of the number of symbols.
• Historical Quotes: Unavailable
• Candles: Unavailable
• Bulk Candles: Unavailable
• Other Endpoints: Unavailable

This makes cached mode particularly cost-effective for bulk quote retrieval using endpoints such as Option Chain and Bulk Stock Quotes.

Requesting Cached Data

GET https://api.marketdata.app/v1/options/chain/SPY/?mode=cached

This request attempts to fulfill the response from Market Data’s cache. If cached data is available, the response is returned at a reduced credit cost.

Using maxage with Cached Mode

The maxage parameter can be combined with mode=cached to control how old cached data may be before it is considered unusable.

How maxage Works

• Purpose: Sets a maximum acceptable age for cached data
• Behavior: If no cached data exists within the specified age window, the API returns an empty response with no credit charge
• Format: Accepts absolute datetimes or relative durations (e.g. 1h, 5min)

Example Scenarios

Assume the most recent cached options chain for AAPL is 3 minutes old.

Scenario 1: Data within maxage limit

GET https://api.marketdata.app/v1/options/chain/AAPL/?mode=cached&maxage=5min

• Result: 203 response with data (1 credit charged)
• Reason: Cached data is newer than 5 minutes

Scenario 2: Data exceeds maxage limit

GET https://api.marketdata.app/v1/options/chain/AAPL/?mode=cached&maxage=1min

• Result: 204 empty response (0 credits charged)
• Reason: Cached data exceeds the specified age limit

Strategic Usage

Using maxage enables efficient fallback logic:

1. First attempt to retrieve cached data with a defined freshness threshold
2. If a 204 response is returned, selectively request live data for required symbols
3. This maximizes cost efficiency while preserving data freshness where it matters

Cached Mode Response Codes

When mode=cached is used, successful responses do not return 200 OK. Instead:

• 203 NON-AUTHORITATIVE INFORMATION – Request succeeded and was fulfilled from cache
• 204 NO CONTENT – No cached data available within constraints; no credits charged

Delayed Mode

The delayed mode returns data delayed by at least 15 minutes. This mode is the default for all free and trial accounts. Paid accounts may also request delayed data explicitly.

Pricing for Delayed Mode

• Pricing is identical to live mode.

Requesting Delayed Data

GET https://api.marketdata.app/v1/options/chain/SPY/?mode=delayed

This request returns market data that is delayed by a minimum of 15 minutes.

Mode Comparison

Feature	Live Mode	Cached Mode	Delayed Mode
Data Timeliness	Real-time	Seconds to minutes old	≥ 15 minutes delayed
Pricing	1 credit per symbol with quote data	1 credit per request	Same as live
Ideal Use-Case	Time-sensitive decisions	Bulk quote retrieval	Non-time-sensitive applications
Default Behavior	Paid accounts (if mode is omitted)	Must specify mode=cached	Free & trial accounts
Paid Accounts Access	✅	✅	✅
Free/Trial Accounts Access	❌	❌	✅

• Choose mode=live when immediate data freshness is required.
• Use mode=cached to reduce credit usage when working with large symbol sets.
• Select mode=delayed for applications where timing precision is not critical.