> ## 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.

# Events

> The scenario's public event timeline.

The event timeline is the public sequence of events that drives prices, news, and filings within a scenario.

## Event timeline

```http theme={null}
GET /events/timeline
```

The public event sequence for the scenario, earnings, macro catalysts, and idiosyncratic events. Events carry a `visible_from` so an `as_of` query returns only what was known at the time. Hidden effects are never exposed publicly.

| Parameter                 | Type    | Required | Default | Description             |
| ------------------------- | ------- | -------- | ------- | ----------------------- |
| `scenario_id`             | string  | Yes      | -       | The world to read from. |
| `ticker`                  | string  | No       | all     | Restrict to one ticker. |
| `as_of`                   | date    | No       | -       | Point-in-time cutoff.   |
| `event_type`              | string  | No       | all     | Filter by event type.   |
| `start_date` / `end_date` | date    | No       | -       | Inclusive window.       |
| `limit`                   | integer | No       | 100     | Page size (max 500).    |
| `offset`                  | integer | No       | 0       | Pagination offset.      |

<CodeGroup>
  ```bash cURL theme={null}
  curl -s "https://api.davidhf.com/events/timeline?scenario_id=<id>&ticker=AAPL&as_of=2026-03-26" \
    -H "X-API-KEY: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  dd.events.timeline(scenario_id="<id>", ticker="AAPL", as_of="2026-03-26")
  ```
</CodeGroup>

```json theme={null}
{
  "events": [
    {
      "event_id": "evt_...",
      "ticker": "AAPL",
      "event_type": "earnings_release",
      "event_date": "2026-03-18",
      "public_release_datetime": "2026-03-18T16:30:00",
      "visible_from": "2026-03-18",
      "public_summary": "Q1 earnings: revenue beat, EPS miss, guidance cut."
    }
  ]
}
```

<Info>
  Events are the spine of a scenario. News, filings, analyst revisions, and price reactions all link back to an event via `source_event_id`, so you can trace any artifact to its cause.
</Info>