{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"HistoricalData.net Stock and Options Coverage API","version":"2.0.4","description":"HistoricalData.net provides public, read-only metadata for historical US stock and options CSV products. No API key is required. The three GET operations return coverage, archive statistics, product offers and sample links; they do not return stock bars, option-chain rows, paid files or private orders.\n\nUse lookupSymbol for one ticker, options underlying or option root. Stock firstDate/lastDate values are daily-file boundaries, possibly including non-trading corporate-action rows; they do not guarantee complete daily or minute coverage. Options lookup checks only the latest published session and counts rows for the resolved underlying. No match in that session does not rule out earlier options history.\n\nFor symbol responses, check each returned product's unavailable flag before found. For getStatus, check stocks.available and options.available; getCatalog nests these flags under status. Preserve the queried symbol, resolved identity, source, scope and relevant data dates in an AI answer. An omitted product was not requested; null statistics are not zero.\n\nUse the servers URL for this deployment. HTTP responses use Cache-Control: no-store. On 429 honor Retry-After; on a failed lookup retry later without reporting missing coverage. Examples are fixed, dated observations or explicitly illustrative failures, not live counts.\n\nThis document describes REST only. The same metadata is available through Model Context Protocol (MCP) at https://historicaldata.net/mcp using Streamable HTTP. Initialize and discover MCP tools separately; connection instructions: https://historicaldata.net/api.html#mcp.","contact":{"email":"info@historicaldata.net"}},"servers":[{"url":"https://historicaldata.net","description":"Origin serving this v2 specification and its API. Append the documented /api paths; do not append /api twice."}],"security":[],"externalDocs":{"url":"https://historicaldata.net/api.html","description":"REST, MCP initialization, examples and interpretation guide"},"tags":[{"name":"Coverage","description":"Single-symbol file and session coverage."},{"name":"Archive status","description":"Product-level statistics and independently dated availability."},{"name":"Products and samples","description":"Public product definitions, listed offers and sample download links."}],"paths":{"/api/symbol/{symbol}":{"get":{"tags":["Coverage"],"operationId":"lookupSymbol","summary":"Check one stock symbol or option underlying/root","description":"Check one symbol in the published files. Select product=stocks or product=options when only that product is relevant; omitted product defaults to all. A single-product response omits the other product block. Dates are source dates, not lookup timestamps.\n\nFor stocks, preserve each records[] entry, including the file identity and firstDate/lastDate. Reused tickers can match separate listing files. For options, preserve both symbol and options.underlying when a root resolves to another underlying. contractsLatestDay belongs to that underlying on latestDate only. Root mapping does not establish equivalence in historical files.\n\nA completed no-match returns HTTP 200, not 404. Check unavailable before found. A combined request can return one unavailable product with a completed result for the other. A requested single-product failure or failure of both products returns HTTP 503. The endpoint does not accept a historical date-range filter.","externalDocs":{"url":"https://historicaldata.net/api.html#symbol-request","description":"Symbol request, complete field paths and a dated response example"},"parameters":[{"name":"symbol","in":"path","required":true,"description":"One ticker, underlying or option root; no company names, full option contracts or symbol lists. Trim surrounding whitespace and URL-encode the value as one path component, including any slash. The server trims and uppercases the decoded value.","schema":{"type":"string","minLength":1,"maxLength":21,"pattern":"^[A-Za-z0-9][A-Za-z0-9.^/-]{0,20}$"},"examples":{"stock":{"value":"AAPL","summary":"Stock ticker or options underlying"},"root":{"value":"SPXW","summary":"Option root; use product=options"},"historical":{"value":"LEH","summary":"Historical stock ticker; use product=stocks"},"punctuation":{"value":"BRK.B","summary":"Ticker with punctuation"}}},{"name":"product","in":"query","required":false,"description":"all checks both products. stocks or options checks only that product and omits the unrequested block. Use lowercase values.","schema":{"type":"string","enum":["all","stocks","options"],"default":"all"}}],"responses":{"200":{"description":"At least one requested product completed its check, including no-match results. Inspect product flags before using coverage.","headers":{"Cache-Control":{"$ref":"#/components/headers/NoStore"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SymbolResponse"},"examples":{"stockFiles":{"summary":"AAPL: matching published stock file","description":"Fixed response snapshot for GET /api/symbol/AAPL?product=stocks. Source date: 2026-09-04. File date boundaries are not complete daily or minute coverage.","value":{"apiVersion":"2","symbol":"AAPL","stocks":{"found":true,"source":"v2-published-stock-files","lastDate":"2026-09-04","scope":"daily-file-boundaries","records":[{"file":"AAPL_day.csv","name":"Apple Inc.","type":"CS","active":true,"delistDate":null,"firstDate":"2003-10-01","lastDate":"2026-09-04","coverage":"2003-10-01 / 2026-09-04","sizeDayBytes":704465,"sizeMinuteBytes":420399078}],"note":"Dates are the first and last rows of each daily file, not a completeness guarantee or minute-bar date range. Minute size is null when no matching file is published. Identity boundaries can be incomplete; a missing symbol is not proof of no historical trading."}}},"reusedTicker":{"summary":"GM: two listing files under one ticker","description":"Fixed response snapshot for GET /api/symbol/GM?product=stocks. Preserve both file identities and their separate dates.","value":{"apiVersion":"2","symbol":"GM","stocks":{"found":true,"source":"v2-published-stock-files","lastDate":"2026-09-04","scope":"daily-file-boundaries","records":[{"file":"GM_day_delisted_2009-06-02.csv","name":"GEN MOTORS CORP","type":"CS","active":false,"delistDate":"2009-06-02","firstDate":"2003-10-01","lastDate":"2009-06-01","coverage":"2003-10-01 / 2009-06-01","sizeDayBytes":158444,"sizeMinuteBytes":61967879},{"file":"GM_day.csv","name":"General Motors Company","type":"CS","active":true,"delistDate":null,"firstDate":"2010-11-18","lastDate":"2026-09-04","coverage":"2010-11-18 / 2026-09-04","sizeDayBytes":464368,"sizeMinuteBytes":190902739}],"note":"Dates are the first and last rows of each daily file, not a completeness guarantee or minute-bar date range. Minute size is null when no matching file is published. Identity boundaries can be incomplete; a missing symbol is not proof of no historical trading."}}},"resolvedRoot":{"summary":"SPXW resolves to SPX for one session","description":"Fixed response snapshot for GET /api/symbol/SPXW?product=options on the 2026-09-04 session. The count belongs to SPX, not SPXW alone or all history.","value":{"apiVersion":"2","symbol":"SPXW","options":{"found":true,"latestDate":"2026-09-04","underlying":"SPX","contractsLatestDay":28650,"source":"v2-published-options-session","scope":"latest-published-session","note":"The count covers the resolved underlying on latestDate only. Not found does not rule out earlier history; root resolution does not establish historical equivalence."}}},"noLatestOptionsMatch":{"summary":"TWTR: no match in the latest checked session","description":"Fixed response snapshot for GET /api/symbol/TWTR?product=options. Earlier options history may still exist; a completed no-match is HTTP 200.","value":{"apiVersion":"2","symbol":"TWTR","options":{"found":false,"latestDate":"2026-09-04","source":"v2-published-options-session","scope":"latest-published-session","note":"The count covers the resolved underlying on latestDate only. Not found does not rule out earlier history; root resolution does not establish historical equivalence."}}},"neitherMatched":{"summary":"No stock file or latest-session options match","description":"Fixed response snapshot for GET /api/symbol/ZZZNOTREAL. Both checks completed. This is not a service failure.","value":{"apiVersion":"2","symbol":"ZZZNOTREAL","stocks":{"found":false,"source":"v2-published-stock-files","lastDate":"2026-09-04","scope":"daily-file-boundaries","records":[],"note":"Dates are the first and last rows of each daily file, not a completeness guarantee or minute-bar date range. Minute size is null when no matching file is published. Identity boundaries can be incomplete; a missing symbol is not proof of no historical trading."},"options":{"found":false,"latestDate":"2026-09-04","source":"v2-published-options-session","scope":"latest-published-session","note":"The count covers the resolved underlying on latestDate only. Not found does not rule out earlier history; root resolution does not establish historical equivalence."}}},"partialAvailability":{"summary":"Illustrative partial failure: stock result remains available","description":"Illustrative HTTP 200 for product=all, combining the dated AAPL stock observation with a simulated unavailable options check. This example is not a report of an outage.","value":{"apiVersion":"2","symbol":"AAPL","stocks":{"found":true,"source":"v2-published-stock-files","lastDate":"2026-09-04","scope":"daily-file-boundaries","records":[{"file":"AAPL_day.csv","name":"Apple Inc.","type":"CS","active":true,"delistDate":null,"firstDate":"2003-10-01","lastDate":"2026-09-04","coverage":"2003-10-01 / 2026-09-04","sizeDayBytes":704465,"sizeMinuteBytes":420399078}],"note":"Dates are the first and last rows of each daily file, not a completeness guarantee or minute-bar date range. Minute size is null when no matching file is published. Identity boundaries can be incomplete; a missing symbol is not proof of no historical trading."},"options":{"found":false,"unavailable":true}}}}}}},"400":{"description":"Invalid symbol encoding, symbol syntax or product value. Correct the request before retrying.","headers":{"Cache-Control":{"$ref":"#/components/headers/NoStore"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Invalid product; use all, stocks or options"}}}},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"The requested single product failed, or both products in an all-products query failed. No coverage conclusion can be drawn.","headers":{"Cache-Control":{"$ref":"#/components/headers/NoStore"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Coverage lookup temporarily unavailable"}}}}}}},"/api/status":{"get":{"tags":["Archive status"],"operationId":"getStatus","summary":"Read archive statistics and latest options-session status","description":"Returns stock statistics and options session status with independent data dates. Stock activeCount, delistedCount and renamedCount are archive lifecycle classifications, not a count of unique ticker strings or guaranteed price files. options.underlyingCount counts distinct underlying values in one published session.\n\nStock firstDate/lastDate are statistics snapshot boundaries. options.statistics carries its own asOf date and may lag options.latestDate. The statistics block can be null even when options.available=true; conversely statistics can remain present when the latest-session check is unavailable.\n\nSource failures are represented by available=false inside an HTTP 200 response, including when both products fail. This operation has no request parameters. Whole-archive dates and counts cannot answer a per-symbol or period-completeness question.","externalDocs":{"url":"https://historicaldata.net/api.html#status-request","description":"Status fields and independent source dates"},"responses":{"200":{"description":"Status envelope, including available=false for any failed product. HTTP 200 alone does not establish source availability.","headers":{"Cache-Control":{"$ref":"#/components/headers/NoStore"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusResponse"},"examples":{"sourceDates":{"summary":"Stock and options statistics with separate dates","description":"Fixed GET /api/status snapshot. Keep each statistics date and the options latestDate with its values; these are not live counters.","value":{"apiVersion":"2","stocks":{"available":true,"source":"v2-stats.json","firstDate":"2003-10-01","lastDate":"2026-09-04","activeCount":15678,"delistedCount":23259,"renamedCount":392,"daySizeBytes":5007089380,"minuteSizeBytes":730836601837,"note":"Security-lifecycle counts include separately classified renamed records. File sizes and dates describe the stated statistics snapshot; minute-file dates must be checked separately."},"options":{"available":true,"source":"v2-published-options-session","scope":"latest-published-session","latestDate":"2026-09-04","underlyingCount":6037,"statistics":{"source":"v2-stats.json","firstDate":"2002-02-08","asOf":"2026-08-25","sizeBytes":460835653838}},"note":"Dates belong to their stated sources. Options statistics may lag the latest published session. Whole-archive dates and counts do not establish coverage for an individual symbol or completeness on every date."}},"missingStatistics":{"summary":"Illustrative available session with missing size statistics","description":"Illustrative HTTP 200: the dated latest-session observation remains available but options.statistics is null. Null does not mean a zero-size archive.","value":{"apiVersion":"2","stocks":{"available":true,"source":"v2-stats.json","firstDate":"2003-10-01","lastDate":"2026-09-04","activeCount":15678,"delistedCount":23259,"renamedCount":392,"daySizeBytes":5007089380,"minuteSizeBytes":730836601837,"note":"Security-lifecycle counts include separately classified renamed records. File sizes and dates describe the stated statistics snapshot; minute-file dates must be checked separately."},"options":{"available":true,"source":"v2-published-options-session","scope":"latest-published-session","latestDate":"2026-09-04","underlyingCount":6037,"statistics":null},"note":"Dates belong to their stated sources. Options statistics may lag the latest published session. Whole-archive dates and counts do not establish coverage for an individual symbol or completeness on every date."}},"unavailableSources":{"summary":"Illustrative HTTP 200 with both status sources unavailable","description":"Illustrative status response for failed source checks. Unlike the symbol endpoint, getStatus preserves its HTTP 200 envelope when both products fail.","value":{"apiVersion":"2","stocks":{"available":false,"error":"Metadata temporarily unavailable; retry later."},"options":{"available":false,"error":"Metadata temporarily unavailable; retry later.","statistics":null},"note":"Dates belong to their stated sources. Options statistics may lag the latest published session. Whole-archive dates and counts do not establish coverage for an individual symbol or completeness on every date."}}}}}},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/catalog":{"get":{"tags":["Products and samples"],"operationId":"getCatalog","summary":"Read datasets, public offers and sample links","description":"Returns datasets[], offers, samples and status. offers.products[].amount is a numeric USD amount for a single-user license; it is not cents. billing distinguishes one-time archive purchases from monthly update subscriptions. License multipliers are in offers.licenses[]. Sample URLs are under samples.stocks.url and samples.options.url.\n\nThe nested status object uses the getStatus structure and can contain available=false while the product definitions, offers and samples remain usable. This operation has no request parameters and does not create orders, charge a card or download any file. Inspect the returned detailsUrl and licenseUrl, and confirm the selected license and final checkout total before purchase.","externalDocs":{"url":"https://historicaldata.net/api.html#catalog-request","description":"Product offers, billing and sample metadata"},"responses":{"200":{"description":"Public catalog. Check status.stocks.available and status.options.available before quoting current archive status.","headers":{"Cache-Control":{"$ref":"#/components/headers/NoStore"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogResponse"}}}},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"headers":{"NoStore":{"description":"HTTP caches must not store the response. Any research observation retained separately must keep its source date and scope.","schema":{"type":"string","const":"no-store"}},"RetryAfter":{"description":"Seconds to wait before retrying a rate-limited request. Reduce repeated requests; there is no guaranteed global quota.","schema":{"type":"string","pattern":"^[0-9]+$","examples":["60"]}}},"responses":{"MethodNotAllowed":{"description":"Unsupported HTTP method. Use GET for these public metadata operations.","headers":{"Cache-Control":{"$ref":"#/components/headers/NoStore"},"Allow":{"description":"HTTP methods accepted by the public REST metadata routes.","schema":{"type":"string","const":"GET, HEAD, OPTIONS"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Use GET for public metadata."}}}},"RateLimited":{"description":"Request rate exceeded. Honor Retry-After and retry later; no coverage conclusion can be drawn.","headers":{"Cache-Control":{"$ref":"#/components/headers/NoStore"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Too many requests; retry later."}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error. Retrying must not convert this into found=false."}},"required":["error"],"additionalProperties":false},"LookupUnavailable":{"description":"A requested product could not be checked. found=false is only a placeholder in this state; unavailable=true takes precedence. No source date, count or coverage absence is established.","type":"object","properties":{"found":{"const":false},"unavailable":{"const":true}},"required":["found","unavailable"],"additionalProperties":false},"StockRecord":{"description":"One published daily-file identity. Multiple records can share the queried ticker but belong to different listings. Confirm identity before joining files.","type":"object","properties":{"file":{"type":"string","description":"Relative filename identifying the published daily file; not a public download URL."},"name":{"anyOf":[{"type":"string","description":"Security name when identity metadata is available."},{"type":"null"}]},"type":{"anyOf":[{"type":"string","description":"Security type such as CS or ETF."},{"type":"null"}]},"active":{"description":"True for a published file in the active listing group; false for a delisted listing file. This is archive classification, not a live exchange-status feed.","type":"boolean"},"delistDate":{"anyOf":[{"type":"string","description":"Delisting date encoded in the published listing filename; distinct from the last row date. Null for a file in the active group.","format":"date"},{"type":"null"}]},"firstDate":{"type":"string","description":"First dated row of this daily file; it may be an event-only row.","format":"date"},"lastDate":{"type":"string","description":"Last dated row of this daily file; not necessarily the last trading date.","format":"date"},"coverage":{"type":"string","description":"Display form of firstDate / lastDate. Parse the separate date fields in software."},"sizeDayBytes":{"type":"integer","minimum":0,"description":"Uncompressed daily CSV bytes."},"sizeMinuteBytes":{"anyOf":[{"type":"integer","minimum":0,"description":"Uncompressed matching minute CSV bytes. Null means no matching minute file, not zero trades. This does not establish minute-file dates."},{"type":"null"}]}},"required":["file","name","type","active","delistDate","firstDate","lastDate","coverage","sizeDayBytes","sizeMinuteBytes"],"additionalProperties":false},"StocksFound":{"description":"Completed stock check with at least one matching published daily file. File boundaries do not guarantee every trading day or minute coverage.","type":"object","properties":{"found":{"const":true},"source":{"const":"v2-published-stock-files"},"lastDate":{"type":"string","description":"Stock statistics date for this lookup source. Not the last row date of every file.","format":"date"},"scope":{"const":"daily-file-boundaries"},"note":{"type":"string","description":"Qualifications that must be retained when interpreting stock coverage."},"records":{"type":"array","items":{"$ref":"#/components/schemas/StockRecord"},"minItems":1}},"required":["found","source","lastDate","scope","note","records"],"additionalProperties":false},"StocksNotFound":{"description":"Completed stock check with no matching published daily file. records is empty. This does not prove the symbol never traded or that another historical name has no file.","type":"object","properties":{"found":{"const":false},"source":{"const":"v2-published-stock-files"},"lastDate":{"type":"string","description":"Stock statistics date for this lookup source. Not the last row date of every file.","format":"date"},"scope":{"const":"daily-file-boundaries"},"note":{"type":"string","description":"Qualifications that must be retained when interpreting stock coverage."},"records":{"type":"array","items":{"$ref":"#/components/schemas/StockRecord"},"maxItems":0}},"required":["found","source","lastDate","scope","note","records"],"additionalProperties":false},"StocksLookup":{"description":"Exactly one stock state: matched files, completed no-match, or unavailable.","oneOf":[{"$ref":"#/components/schemas/StocksFound"},{"$ref":"#/components/schemas/StocksNotFound"},{"$ref":"#/components/schemas/LookupUnavailable"}]},"OptionsFound":{"description":"Completed options check with a resolved underlying in the latest published session. The underlying and count are required only in this state.","type":"object","properties":{"found":{"const":true},"source":{"const":"v2-published-options-session"},"scope":{"const":"latest-published-session"},"latestDate":{"type":"string","description":"Published session checked, including when found=false. Not the response creation date.","format":"date"},"note":{"type":"string","description":"Qualifications for the current-session count and root mapping; earlier history remains a separate question."},"underlying":{"type":"string","description":"Resolved CSV underlying for this session; can differ from the query root. Preserve both query and resolved name."},"contractsLatestDay":{"type":"integer","minimum":0,"description":"Contract rows for the resolved underlying on latestDate only. Not an all-history total or a root-only count."}},"required":["found","source","scope","latestDate","note","underlying","contractsLatestDay"],"additionalProperties":false},"OptionsNotFound":{"description":"Completed options check with no latest-session match. latestDate is retained; underlying and contractsLatestDay are absent, not null or zero. Earlier options history may still exist.","type":"object","properties":{"found":{"const":false},"source":{"const":"v2-published-options-session"},"scope":{"const":"latest-published-session"},"latestDate":{"type":"string","description":"Published session checked, including when found=false. Not the response creation date.","format":"date"},"note":{"type":"string","description":"Qualifications for the current-session count and root mapping; earlier history remains a separate question."}},"required":["found","source","scope","latestDate","note"],"additionalProperties":false},"OptionsLookup":{"description":"Exactly one options state: latest-session match, completed no-match, or unavailable.","oneOf":[{"$ref":"#/components/schemas/OptionsFound"},{"$ref":"#/components/schemas/OptionsNotFound"},{"$ref":"#/components/schemas/LookupUnavailable"}]},"SymbolResponse":{"description":"Successful HTTP response with at least one completed product check. product=all returns stocks and options; a single-product query omits the unrequested block. One unavailable block can coexist with a completed check; only-unavailable results use HTTP 503 and the Error schema.","type":"object","properties":{"apiVersion":{"type":"string","const":"2"},"symbol":{"type":"string","description":"Trimmed, uppercase query symbol. Root queries may differ from options.underlying."},"stocks":{"$ref":"#/components/schemas/StocksLookup"},"options":{"$ref":"#/components/schemas/OptionsLookup"}},"required":["apiVersion","symbol"],"additionalProperties":false,"anyOf":[{"required":["stocks"],"properties":{"stocks":{"oneOf":[{"$ref":"#/components/schemas/StocksFound"},{"$ref":"#/components/schemas/StocksNotFound"}]}}},{"required":["options"],"properties":{"options":{"oneOf":[{"$ref":"#/components/schemas/OptionsFound"},{"$ref":"#/components/schemas/OptionsNotFound"}]}}}]},"StockStatus":{"description":"Stock statistics availability. Failed statistics expose available=false and error without invented dates or zero counts.","oneOf":[{"type":"object","properties":{"available":{"const":false},"error":{"type":"string","description":"Why stock statistics are unavailable; retry later."}},"required":["available","error"],"additionalProperties":false},{"type":"object","properties":{"available":{"const":true},"source":{"const":"v2-stats.json"},"firstDate":{"type":"string","description":"Earliest stock date in the statistics snapshot, not a start date for every symbol.","format":"date"},"lastDate":{"type":"string","description":"Latest stock date represented by the statistics snapshot, not completeness through that date for every file.","format":"date"},"activeCount":{"type":"integer","minimum":0,"description":"Active security-lifecycle records in the stock statistics snapshot; not a promise of distinct ticker strings or price files."},"delistedCount":{"type":"integer","minimum":0,"description":"Delisted security-lifecycle records in the stock statistics snapshot; reused tickers can represent separate listings."},"renamedCount":{"type":"integer","minimum":0,"description":"Separately classified renamed identity records; not necessarily separate price files."},"daySizeBytes":{"type":"integer","minimum":0,"description":"Uncompressed daily CSV bytes represented by the stock statistics snapshot."},"minuteSizeBytes":{"type":"integer","minimum":0,"description":"Uncompressed minute CSV bytes represented by the stock statistics snapshot."},"note":{"type":"string","description":"Scope of the source statistics."},"releaseId":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"Immutable stock metadata release; SHA256 of its descriptor."},"coverage":{"type":"object","description":"Separate day_by_symbol, minute_by_symbol, day_by_date and minute_by_date coverage. Null archive dates mean unknown; incremental dates never substitute for archive bounds.","additionalProperties":true}},"required":["available","source","firstDate","lastDate","activeCount","delistedCount","renamedCount","daySizeBytes","minuteSizeBytes","note"],"additionalProperties":false}]},"OptionStatistics":{"description":"Archive-level options size statistics, independent of the latest-session lookup. A snapshot can lag the latest published session.","type":"object","properties":{"source":{"const":"v2-stats.json"},"firstDate":{"type":"string","description":"Earliest options date in the statistics snapshot; not the start date for each underlying.","format":"date"},"asOf":{"type":"string","description":"Latest options date represented by these size statistics; may precede options.latestDate.","format":"date"},"sizeBytes":{"type":"integer","minimum":0,"description":"Uncompressed delivered options CSV bytes represented by this statistics snapshot."}},"required":["source","firstDate","asOf","sizeBytes"],"additionalProperties":false},"OptionStatus":{"description":"Availability of the verified latest options session. statistics is independently available: it can be null in either state, or present while the session check is unavailable.","oneOf":[{"type":"object","properties":{"available":{"const":false},"error":{"type":"string","description":"Why the latest options session cannot be verified; retry later."},"statistics":{"anyOf":[{"$ref":"#/components/schemas/OptionStatistics"},{"type":"null"}]}},"required":["available","error","statistics"],"additionalProperties":false},{"type":"object","properties":{"available":{"const":true},"source":{"const":"v2-published-options-session"},"scope":{"const":"latest-published-session"},"latestDate":{"type":"string","description":"Published session checked, not an archive-wide completeness guarantee.","format":"date"},"underlyingCount":{"type":"integer","minimum":0,"description":"Distinct CSV underlying values in this one session, not distinct historical roots or an all-history count."},"statistics":{"anyOf":[{"$ref":"#/components/schemas/OptionStatistics"},{"type":"null"}]}},"required":["available","source","scope","latestDate","underlyingCount","statistics"],"additionalProperties":false}]},"StatusResponse":{"description":"Source-dated status envelope. HTTP 200 is returned even if either or both products have available=false. Interpret each source independently.","type":"object","properties":{"apiVersion":{"type":"string","const":"2"},"stocks":{"$ref":"#/components/schemas/StockStatus"},"options":{"$ref":"#/components/schemas/OptionStatus"},"note":{"type":"string","description":"Cross-source date and scope qualifications."}},"required":["apiVersion","stocks","options","note"],"additionalProperties":false},"Offer":{"type":"object","properties":{"id":{"type":"string","description":"Public offer identifier; not an order or download credential."},"name":{"type":"string","description":"Product offer name."},"product":{"type":"string","enum":["stocks","options"]},"amount":{"anyOf":[{"type":"integer","minimum":0,"description":"USD amount, not cents, for a single-user license. Null means unavailable for new purchase. Apply the selected license multiplier; confirm the final checkout total."},{"type":"null"}]},"availableForNewPurchase":{"type":"boolean","description":"False means the offer cannot currently be purchased; existing orders are unaffected."},"pricePhase":{"type":"string","description":"Current full-archive pricing phase identifier, when applicable."},"note":{"type":"string","description":"Availability qualification for this offer, when applicable."},"billing":{"type":"string","enum":["one-time","monthly"],"description":"one-time purchases an archive; monthly is a separately billed update subscription."},"history":{"type":"string","description":"Historical window or update scope included in this offer; coverage still varies by security."},"includedUpdateMonths":{"type":"integer","minimum":0,"description":"Update months bundled with the archive purchase; zero for a separately billed subscription. Included archive updates do not renew automatically."},"includesDailyBars":{"description":"For stock offers, whether daily bars are included. Omitted for options products; absence is not false.","type":"boolean"},"detailsUrl":{"description":"Product-page pricing section for reviewing this offer. Following the URL does not create an order.","type":"string","format":"uri"}},"required":["id","name","product","amount","billing","history","includedUpdateMonths","detailsUrl"],"additionalProperties":false},"Pricing":{"description":"Public listed offers and license metadata. Returned under catalog.offers, or directly by the MCP get_pricing tool. This is not a personalized checkout quote.","type":"object","properties":{"apiVersion":{"type":"string","const":"2"},"currency":{"const":"USD"},"priceBasis":{"const":"single-user"},"products":{"type":"array","items":{"$ref":"#/components/schemas/Offer"}},"pricingState":{"type":"object","properties":{"authority":{"type":"string","enum":["static","live"]},"phase":{"type":"string","description":"Current price phase."},"status":{"type":"string","enum":["active","paused"]},"startedAt":{"anyOf":[{"type":"string","description":"Actual activation time; null before an experiment starts.","format":"date-time"},{"type":"null"}]}},"required":["authority","phase","status","startedAt"],"additionalProperties":false},"licenses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["single","team","organization"]},"maxUsers":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"description":"Maximum authorized users. Null means unlimited users within the stated organization scope, not unrestricted redistribution."},"priceMultiplier":{"type":"integer","minimum":0,"description":"Multiplier applied to the listed single-user amount."},"scope":{"type":"string","description":"Additional license scope, when provided; organization coverage is one legal entity."}},"required":["id","maxUsers","priceMultiplier"],"additionalProperties":false}},"licenseUrl":{"description":"Published data license and usage terms.","type":"string","format":"uri"},"archiveDownloadDays":{"type":"integer","minimum":0,"description":"Initial archive download-link validity in days from purchase. Applies to all one-time archive offers; included updates and monthly subscriptions have separate access periods.","examples":[21]},"archiveRefundRequestDays":{"type":"integer","minimum":0,"description":"Days from purchase in which a full or partial usage-based archive refund must be requested. Replacement or extended download links do not restart this period. This deadline does not limit the independent delivery-failure commitment or describe monthly subscription cancellation.","examples":[21]},"refundPolicyUrl":{"description":"Full archive refund terms, usage tiers, download counting and separate subscription and delivery commitments.","type":"string","format":"uri"},"delivery":{"type":"string","description":"Delivery channels, archive download validity and separate included-update arrangements."},"refunds":{"type":"string","description":"Archive refund eligibility and usage units. Options count only calendar months for which all available daily files within the purchased archive have been downloaded; partially downloaded months count as zero, and zero fully downloaded months qualifies for a 100% usage-based refund. Also describes the replacement-link rule, subscription cancellation and independent delivery-failure commitment. Read the full terms at refundPolicyUrl."},"note":{"type":"string","description":"Offer and checkout qualifications."}},"required":["apiVersion","currency","priceBasis","products","pricingState","licenses","licenseUrl","archiveDownloadDays","archiveRefundRequestDays","refundPolicyUrl","delivery","refunds","note"],"additionalProperties":false},"Samples":{"description":"Public sample links and extraction scope. Returned under catalog.samples, or directly by MCP get_free_sample. The endpoint returns metadata only; download a ZIP separately.","type":"object","properties":{"apiVersion":{"type":"string","const":"2"},"coverage":{"type":"object","properties":{"firstDate":{"type":"string","description":"Inclusive start of the sample extraction window.","format":"date"},"lastDate":{"type":"string","description":"Inclusive end of the calendar extraction window. Not necessarily a trading day or the last row in every file.","format":"date"}},"required":["firstDate","lastDate"],"additionalProperties":false},"stocks":{"type":"object","properties":{"symbols":{"description":"Requested sample stock tickers; individual listing coverage can end within the sample window.","type":"array","items":{"type":"string"}},"dailyColumns":{"type":"integer","minimum":0,"description":"Columns in each daily CSV."},"minuteColumns":{"type":"integer","minimum":0,"description":"Columns in each minute CSV."},"url":{"description":"Public stock sample ZIP download URL.","type":"string","format":"uri"},"docs":{"description":"Stock sample instructions and scope.","type":"string","format":"uri"}},"required":["symbols","dailyColumns","minuteColumns","url","docs"],"additionalProperties":false},"options":{"type":"object","properties":{"underlyings":{"description":"CSV underlying values included in the historical sample. SPX and SPXW are separate values here; do not replace them using a current-session root mapping.","type":"array","items":{"type":"string"}},"columns":{"type":"integer","minimum":0,"description":"Columns in each options CSV."},"url":{"description":"Public options sample ZIP download URL.","type":"string","format":"uri"},"docs":{"description":"Options sample instructions and scope.","type":"string","format":"uri"}},"required":["underlyings","columns","url","docs"],"additionalProperties":false},"note":{"type":"string","description":"Sample coverage qualifications."}},"required":["apiVersion","coverage","stocks","options","note"],"additionalProperties":false},"CatalogResponse":{"description":"Dataset definitions, listed offers, sample links and nested status. Product information remains usable if a status source fails.","type":"object","properties":{"apiVersion":{"type":"string","const":"2"},"site":{"description":"Origin serving this catalog and its public documentation.","type":"string","format":"uri"},"datasets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Dataset family identifier, such as stocks or options."},"name":{"type":"string","description":"Dataset name."},"format":{"const":"CSV"},"frequencies":{"description":"Supported data intervals; not API price-data endpoints.","type":"array","items":{"type":"string"}},"declaredStart":{"type":"string","description":"Product-level start, not a coverage start for every security.","format":"date"},"docs":{"type":"string","format":"uri"},"schema":{"type":"string","format":"uri"},"limits":{"type":"string","format":"uri"}},"required":["id","name","format","frequencies","declaredStart","docs","schema","limits"],"additionalProperties":false}},"offers":{"$ref":"#/components/schemas/Pricing"},"samples":{"$ref":"#/components/schemas/Samples"},"status":{"$ref":"#/components/schemas/StatusResponse"},"methodology":{"description":"Data methodology and calculation conventions.","type":"string","format":"uri"},"contact":{"type":"string","description":"Contact for period-specific coverage questions.","format":"email"}},"required":["apiVersion","site","datasets","offers","samples","status","methodology","contact"],"additionalProperties":false}}}}