Historical research packs: backtests, provenance and downloads

Catalog and downloads

Versioned offline research accompanies historical income responses through metrics.research. The pack describes the strategy family, not the returned candidate or its exact parameters. No backtest runs inside the API request.

GET /v1/research/packs?symbol=SPY&strategy=covered_call
GET /v1/research/packs/{packId}
GET /v1/research/packs/{packId}/artifacts/{name}

Endpoint reference: catalog, manifest and artifact download.

Host: historical.flashalpha.com. Auth: X-Api-Key, Alpha or Enterprise. All three accept optional at; the catalog also accepts symbol and strategy. Availability requires deployment of the corresponding API release and the immutable catalog. Missing catalog configuration returns an empty collection.

Historical availability and retrospective discovery

A pack is eligible only if its published_at_utc, definition_frozen_at_utc and data_cutoff_utc are all no later than the requested instant. The check applies to manifests and downloads. Old evaluation data does not make a newly published study available to an earlier replay.

{
  "status": "no_pack_available_as_of_request",
  "pack_ids": [],
  "scope": "strategy_family_research_not_a_backtest_of_this_candidate",
  "as_of_catalog_url": "/v1/research/packs?symbol=SPY&strategy=covered_call&at=2026-10-12T20%3A00%3A00Z",
  "retrospective_catalog_url": "/v1/research/packs?symbol=SPY&strategy=covered_call"
}

This is an abbreviated field example, not a complete response. as_of_utc also records the replay cutoff. An explicit retrospective catalog request omits at and can discover later research. It must not be treated as evidence available to a historical trading decision.

The first pack records published_at_utc on 2026-10-16 when the offline publication was built. Replays before that timestamp return no pack even though its evaluation data ends in 2025; retrospective discovery is the useful path for those dates. The manifest timestamp alone does not establish that the API or catalog is deployed.

What a pack contains

Downloads allow only manifest-listed artifacts and verify byte length/SHA-256. A mismatch returns 503; an unlisted artifact returns 404. The manifest itself is obtained from the pack route. Download HTML is an attachment; for local browsing download related files together, or use the reproduction archive for accounting regeneration. Authentication is required for captured-input downloads.

First income pilot

Pack ID: income-spy-qqq-2024-2025-v1-db139753fe8b. The study evaluates SPY/QQQ covered calls and cash-secured puts on first-session monthly entries, expiry nearest 30 days within 28–35 DTE, and a five-session-before-expiry close. It starts each independent portfolio with USD 100,000, uses one contract, and uses 100 shares for covered calls. All four 2025 baseline portfolios complete. QQQ runs containing 2024 are withheld at missing held-contract marks.

Options sell at bid and buy back at ask; shares buy at ask and sell at bid. Baseline costs are USD 1 per option side plus USD 0.01/share adverse slippage. Idle cash earns zero interest; dividends are unreinvested entitlement-based receivables. Benchmark rankings are conditional on zero cash yield and can change when interest accrues; this version has no cash-interest scenario. Tax and intraday drawdown are excluded. Mechanical assignment is a separate scenario, not observed exercise or a worst-case bound.

The 2025 chronological holdout is retrospective. Accounting checks do not certify Greeks, source integrity, original OI publication, fills or predictive value. Samples are small and overlapping scenarios are dependent. Missing QQQ data cannot be converted into a complete return by forward filling.

Trader-context endpoint study

Pack ID: trader-context-spy-qqq-2022-2025-v2-34105d743fac, which supersedes trader-context-spy-qqq-2022-2025-v1-bd47765cb549 (its manifest lists the five corrections). It replays expiry impact, strike dependency, term-structure gamma concentration and yield enhancement at 15:55 ET on every 2022–2025 SPY and QQQ session and measures the next session; yield-enhancement picks are held to expiry. Catalog strategies: expiry_impact, strike_dependency, gamma_concentration, covered_call, cash_secured_put. Results: Does expiring gamma move the market?

Reproduce and deploy

python income_pilot.py --capture-root capture --pack-root regenerated
python audit_income_pack.py regenerated/income-spy-qqq-2024-2025-v1-db139753fe8b
python -m unittest test_income_pilot

Extract reproduce.zip first; accounting regeneration needs no database or credentials. Ten result/accounting files reproduced byte for byte with Python 3.13.7. Captured IV/delta come from the API pricer and are not independently recomputed by the portfolio engine.

For operators, provision complete immutable pack directories under the deployment host's /data/research-packs catalog. Compose mounts that directory at /research-packs read-only and sets Historical__ResearchPackDirectory=/research-packs. The API does not generate, copy or install packs automatically; the catalog must be provisioned separately. Rule, input or code revisions require a new pack identity.

See historical trader-context routes for source-health status, earnings limitations and income arithmetic.