> ## Documentation Index
> Fetch the complete documentation index at: https://docs.davidhf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scenarios

> Browse, inspect, and validate the synthetic market worlds David provides.

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](/concepts/scenarios) for the concept.

<Info>
  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 [founders@davidhf.com](mailto:founders@davidhf.com).
</Info>

## List scenarios

```http theme={null}
GET /scenarios
```

Browse available scenarios with filters. This is usually where you start, find a `scenario_id`, then query its data.

| Parameter                | Type    | Required | Default | Description                                     |
| ------------------------ | ------- | -------- | ------- | ----------------------------------------------- |
| `status`                 | string  | No       | -       | Filter by status (e.g. `ready`).                |
| `path_mode`              | enum    | No       | -       | `historical_context` \| `future_branch`.        |
| `min_ticker_count`       | integer | No       | -       | Only scenarios with at least this many tickers. |
| `max_scenario_day_count` | integer | No       | -       | Only scenarios at most this many trading days.  |
| `healthy_only`           | boolean | No       | false   | Only scenarios that passed validation.          |
| `limit`                  | integer | No       | 20      | Page size (max 1000).                           |
| `offset`                 | integer | No       | 0       | Pagination offset.                              |

<CodeGroup>
  ```bash cURL theme={null}
  curl -s "https://api.davidhf.com/scenarios?path_mode=future_branch&healthy_only=true&limit=5" \
    -H "X-API-KEY: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  dd.scenarios.list(path_mode="future_branch", healthy_only=True, limit=5)
  ```
</CodeGroup>

```json theme={null}
{
  "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", "...": "..." }
    }
  ]
}
```

<Tip>
  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.
</Tip>

## Get a scenario

```http theme={null}
GET /scenarios/{scenario_id}
```

Returns the scenario plus its `available_tickers`.

<CodeGroup>
  ```bash cURL theme={null}
  curl -s "https://api.davidhf.com/scenarios/6724c7d1-1b34-5da4-bc69-5ab0ef99c3c0" \
    -H "X-API-KEY: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  dd.scenarios.get("6724c7d1-1b34-5da4-bc69-5ab0ef99c3c0")
  ```
</CodeGroup>

```json theme={null}
{
  "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

```http theme={null}
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.

<CodeGroup>
  ```bash cURL theme={null}
  curl -s "https://api.davidhf.com/scenarios/6724c7d1-1b34-5da4-bc69-5ab0ef99c3c0/validation" \
    -H "X-API-KEY: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  dd.scenarios.validation("6724c7d1-1b34-5da4-bc69-5ab0ef99c3c0")
  ```
</CodeGroup>