Skip to main content
Scenarios are the worlds you query. David builds and curates the full library; you browse it and pull data from any scenario. Use these endpoints to list scenarios, read a scenario’s details, and check its validation report. See Scenarios for the concept.
Scenario generation is handled by David. Every scenario in the library is pre-built, validated, and immutable, so results are reproducible across teams and runs. If you need a world with specific characteristics that the library doesn’t cover, contact investors@davidhf.com.

​
List scenarios

GET /scenarios
Browse available scenarios with filters. This is usually where you start, find a scenario_id, then query its data.
ParameterTypeRequiredDefaultDescription
statusstringNo-Filter by status (e.g. ready).
path_modeenumNo-historical_context | future_branch.
min_ticker_countintegerNo-Only scenarios with at least this many tickers.
max_scenario_day_countintegerNo-Only scenarios at most this many trading days.
healthy_onlybooleanNofalseOnly scenarios that passed validation.
limitintegerNo20Page size (max 1000).
offsetintegerNo0Pagination offset.
curl -s "https://api.davidhf.com/scenarios?path_mode=future_branch&healthy_only=true&limit=5" \
  -H "X-API-KEY: YOUR_API_KEY"

{
  "scenarios": [
    {
      "id": "81e62b3b-17bd-5f55-b9a4-5f36ae6392f3",
      "status": "ready",
      "scenario_type": "earnings_week",
      "seed": 120001,
      "name": "Contested election and policy volatility ...",
      "start_date": "2026-09-24",
      "end_date": "2030-08-05",
      "current_date": "2026-09-24",
      "generator_version": "synthetic-finance-generator-v0.1",
      "calibration_version": "local-calibration-v0.1",
      "public_summary": { "scenario_theme": "election_policy_volatility", "path_mode": "future_branch", "...": "..." }
    }
  ]
}
Filter by dataset_split characteristics, path_mode, ticker count, and horizon to assemble train / validation / test / holdout sets from the curated library, no generation required.

​
Get a scenario

GET /scenarios/{scenario_id}
Returns the scenario plus its available_tickers. 
curl -s "https://api.davidhf.com/scenarios/6724c7d1-1b34-5da4-bc69-5ab0ef99c3c0" \
  -H "X-API-KEY: YOUR_API_KEY"

{
  "scenario": {
    "id": "6724c7d1-1b34-5da4-bc69-5ab0ef99c3c0",
    "status": "ready",
    "start_date": "1993-05-28",
    "end_date": "2023-05-08",
    "public_summary": {
      "macro_regime": "inflation_shock",
      "scenario_theme": "geopolitical_war_energy_shock",
      "scenario_title": "War-driven energy shock: shipping-lane escalation ...",
      "path_mode": "historical_context",
      "market_description": "A regional war disrupts energy supply ...",
      "agent_task": "Separate durable commodity winners from companies with temporary price spikes ...",
      "market_mechanics": ["energy and materials gain on commodity pricing power", "..."]
    },
    "available_tickers": ["AAPL", "MSFT", "NVDA", "AMZN", "GOOGL", "..."]
  }
}

​
Validation report

GET /scenarios/{scenario_id}/validation
The machine-checkable consistency report for the scenario: income-statement arithmetic, balance-sheet identity, cash reconciliation, EPS reconciliation, OHLC and volume invariants, event-day volume spikes, earnings price-reaction sign, and artifact-leakage checks. Every scenario David ships passes these checks. 
curl -s "https://api.davidhf.com/scenarios/6724c7d1-1b34-5da4-bc69-5ab0ef99c3c0/validation" \
  -H "X-API-KEY: YOUR_API_KEY"