# Calendar

## Get Clock

`v1.calendar.get_clock()  -> CalendarGetClockResponse`

**get** `/v1/clock`

Returns the current server time in UTC.

### Returns

- `class CalendarGetClockResponse: …`

  - `data: ClockDetail`

    Current server time and market clock information

    - `clock: datetime`

      Current server time in UTC

### Example

```python
from clear_street import ClearStreet

client = ClearStreet(
    api_key="My API Key",
)
response = client.v1.calendar.get_clock()
print(response)
```

#### Response

```json
{
  "data": {
    "clock": "2025-03-01T03:35:00.000000000Z"
  },
  "error": null,
  "metadata": {
    "request_id": "1b2c3d4e-5f6a-7b8c-9d0e-1f2a3b4c5d6e"
  }
}
```

## Get Market Hours Calendar.

`v1.calendar.get_market_hours_calendar(CalendarGetMarketHoursCalendarParams**kwargs)  -> CalendarGetMarketHoursCalendarResponse`

**get** `/v1/calendars/market-hours`

Retrieves comprehensive trading hours including pre-market, regular, and after-hours sessions.
Returns market status, session times, and next session schedules.

### Parameters

- `date: str`

  The date to query market hours for (YYYY-MM-DD). Defaults to today.

- `market: Optional[MarketType]`

  Market type to query (us_equities, us_options). If omitted, returns all markets.

  - `"us_equities"`

  - `"us_options"`

### Returns

- `class CalendarGetMarketHoursCalendarResponse: …`

  - `data: MarketHoursDetailList`

    - `current_time: datetime`

      Current time in market timezone with offset

    - `date: date`

      The date for which market hours are provided

    - `market: MarketType`

      Market type identifier

      - `"us_equities"`

      - `"us_options"`

    - `market_name: str`

      Human-readable market name

    - `next_sessions: TradingSessions`

      Next trading day's session schedules (without time_until fields)

      - `after_hours: Optional[SessionSchedule]`

        After-hours session schedule, null if not available

        - `close: datetime`

          Session close timestamp with timezone offset

        - `open: datetime`

          Session open timestamp with timezone offset

        - `time_until_close: Optional[str]`

          ISO 8601 duration until session closes. Null if session is not currently open.

        - `time_until_open: Optional[str]`

          ISO 8601 duration until session opens. Null if session has already started or closed.

      - `pre_market: Optional[SessionSchedule]`

        Pre-market session schedule, null if not available

      - `regular: Optional[SessionSchedule]`

        Regular trading session schedule, null if holiday/weekend

    - `status: MarketStatus`

      Market status information

      - `day_type: DayType`

        The type of trading day

        - `"TRADING_DAY"`

        - `"EARLY_CLOSE"`

        - `"HOLIDAY"`

        - `"WEEKEND"`

      - `is_open: bool`

        Whether the market is currently open (real-time)

      - `current_session: Optional[MarketSessionType]`

        Current session type if market is open, null if closed

        - `"pre_market"`

        - `"regular"`

        - `"after_hours"`

    - `timezone: str`

      IANA timezone identifier for the market

    - `today_sessions: TradingSessions`

      Trading session schedules for the requested date with time_until fields

### Example

```python
from clear_street import ClearStreet

client = ClearStreet(
    api_key="My API Key",
)
response = client.v1.calendar.get_market_hours_calendar(
    date="date",
)
print(response)
```

#### Response

```json
{
  "data": [
    {
      "current_time": "2025-11-28T11:00:00-05:00",
      "date": "2025-11-28",
      "market": "us_equities",
      "market_name": "US Equities",
      "next_sessions": {
        "after_hours": {
          "close": "2025-12-01T20:00:00-05:00",
          "open": "2025-12-01T16:00:00-05:00"
        },
        "pre_market": {
          "close": "2025-12-01T09:30:00-05:00",
          "open": "2025-12-01T04:00:00-05:00"
        },
        "regular": {
          "close": "2025-12-01T16:00:00-05:00",
          "open": "2025-12-01T09:30:00-05:00"
        }
      },
      "status": {
        "current_session": "regular",
        "day_type": "EARLY_CLOSE",
        "is_open": true
      },
      "timezone": "America/New_York",
      "today_sessions": {
        "pre_market": {
          "close": "2025-11-28T09:30:00-05:00",
          "open": "2025-11-28T04:00:00-05:00"
        },
        "regular": {
          "close": "2025-11-28T13:00:00-05:00",
          "open": "2025-11-28T09:30:00-05:00",
          "time_until_close": "PT2H"
        }
      }
    }
  ],
  "error": null,
  "metadata": {
    "request_id": "3d4e5f6a-7b8c-9d0e-1f2a-3b4c5d6e7f8a"
  }
}
```

## Domain Types

### Clock Detail

- `class ClockDetail: …`

  Current server time and market clock information

  - `clock: datetime`

    Current server time in UTC

### Day Type

- `Literal["TRADING_DAY", "EARLY_CLOSE", "HOLIDAY", "WEEKEND"]`

  Day type for market hours - indicates the type of trading day

  - `"TRADING_DAY"`

  - `"EARLY_CLOSE"`

  - `"HOLIDAY"`

  - `"WEEKEND"`

### Market Hours Detail

- `class MarketHoursDetail: …`

  Comprehensive market hours information for a specific market and date

  - `current_time: datetime`

    Current time in market timezone with offset

  - `date: date`

    The date for which market hours are provided

  - `market: MarketType`

    Market type identifier

    - `"us_equities"`

    - `"us_options"`

  - `market_name: str`

    Human-readable market name

  - `next_sessions: TradingSessions`

    Next trading day's session schedules (without time_until fields)

    - `after_hours: Optional[SessionSchedule]`

      After-hours session schedule, null if not available

      - `close: datetime`

        Session close timestamp with timezone offset

      - `open: datetime`

        Session open timestamp with timezone offset

      - `time_until_close: Optional[str]`

        ISO 8601 duration until session closes. Null if session is not currently open.

      - `time_until_open: Optional[str]`

        ISO 8601 duration until session opens. Null if session has already started or closed.

    - `pre_market: Optional[SessionSchedule]`

      Pre-market session schedule, null if not available

    - `regular: Optional[SessionSchedule]`

      Regular trading session schedule, null if holiday/weekend

  - `status: MarketStatus`

    Market status information

    - `day_type: DayType`

      The type of trading day

      - `"TRADING_DAY"`

      - `"EARLY_CLOSE"`

      - `"HOLIDAY"`

      - `"WEEKEND"`

    - `is_open: bool`

      Whether the market is currently open (real-time)

    - `current_session: Optional[MarketSessionType]`

      Current session type if market is open, null if closed

      - `"pre_market"`

      - `"regular"`

      - `"after_hours"`

  - `timezone: str`

    IANA timezone identifier for the market

  - `today_sessions: TradingSessions`

    Trading session schedules for the requested date with time_until fields

### Market Hours Detail List

- `List[MarketHoursDetail]`

  - `current_time: datetime`

    Current time in market timezone with offset

  - `date: date`

    The date for which market hours are provided

  - `market: MarketType`

    Market type identifier

    - `"us_equities"`

    - `"us_options"`

  - `market_name: str`

    Human-readable market name

  - `next_sessions: TradingSessions`

    Next trading day's session schedules (without time_until fields)

    - `after_hours: Optional[SessionSchedule]`

      After-hours session schedule, null if not available

      - `close: datetime`

        Session close timestamp with timezone offset

      - `open: datetime`

        Session open timestamp with timezone offset

      - `time_until_close: Optional[str]`

        ISO 8601 duration until session closes. Null if session is not currently open.

      - `time_until_open: Optional[str]`

        ISO 8601 duration until session opens. Null if session has already started or closed.

    - `pre_market: Optional[SessionSchedule]`

      Pre-market session schedule, null if not available

    - `regular: Optional[SessionSchedule]`

      Regular trading session schedule, null if holiday/weekend

  - `status: MarketStatus`

    Market status information

    - `day_type: DayType`

      The type of trading day

      - `"TRADING_DAY"`

      - `"EARLY_CLOSE"`

      - `"HOLIDAY"`

      - `"WEEKEND"`

    - `is_open: bool`

      Whether the market is currently open (real-time)

    - `current_session: Optional[MarketSessionType]`

      Current session type if market is open, null if closed

      - `"pre_market"`

      - `"regular"`

      - `"after_hours"`

  - `timezone: str`

    IANA timezone identifier for the market

  - `today_sessions: TradingSessions`

    Trading session schedules for the requested date with time_until fields

### Market Session Type

- `Literal["pre_market", "regular", "after_hours"]`

  Session type for market hours

  - `"pre_market"`

  - `"regular"`

  - `"after_hours"`

### Market Status

- `class MarketStatus: …`

  Market status information

  - `day_type: DayType`

    The type of trading day

    - `"TRADING_DAY"`

    - `"EARLY_CLOSE"`

    - `"HOLIDAY"`

    - `"WEEKEND"`

  - `is_open: bool`

    Whether the market is currently open (real-time)

  - `current_session: Optional[MarketSessionType]`

    Current session type if market is open, null if closed

    - `"pre_market"`

    - `"regular"`

    - `"after_hours"`

### Market Type

- `Literal["us_equities", "us_options"]`

  Market type for market hours calendar endpoint

  - `"us_equities"`

  - `"us_options"`

### Session Schedule

- `class SessionSchedule: …`

  Session schedule with open and close timestamps

  - `close: datetime`

    Session close timestamp with timezone offset

  - `open: datetime`

    Session open timestamp with timezone offset

  - `time_until_close: Optional[str]`

    ISO 8601 duration until session closes. Null if session is not currently open.

  - `time_until_open: Optional[str]`

    ISO 8601 duration until session opens. Null if session has already started or closed.

### Trading Sessions

- `class TradingSessions: …`

  Trading sessions for a market day with full timestamps

  - `after_hours: Optional[SessionSchedule]`

    After-hours session schedule, null if not available

    - `close: datetime`

      Session close timestamp with timezone offset

    - `open: datetime`

      Session open timestamp with timezone offset

    - `time_until_close: Optional[str]`

      ISO 8601 duration until session closes. Null if session is not currently open.

    - `time_until_open: Optional[str]`

      ISO 8601 duration until session opens. Null if session has already started or closed.

  - `pre_market: Optional[SessionSchedule]`

    Pre-market session schedule, null if not available

  - `regular: Optional[SessionSchedule]`

    Regular trading session schedule, null if holiday/weekend

### Calendar Get Clock Response

- `class CalendarGetClockResponse: …`

  - `data: ClockDetail`

    Current server time and market clock information

    - `clock: datetime`

      Current server time in UTC

### Calendar Get Market Hours Calendar Response

- `class CalendarGetMarketHoursCalendarResponse: …`

  - `data: MarketHoursDetailList`

    - `current_time: datetime`

      Current time in market timezone with offset

    - `date: date`

      The date for which market hours are provided

    - `market: MarketType`

      Market type identifier

      - `"us_equities"`

      - `"us_options"`

    - `market_name: str`

      Human-readable market name

    - `next_sessions: TradingSessions`

      Next trading day's session schedules (without time_until fields)

      - `after_hours: Optional[SessionSchedule]`

        After-hours session schedule, null if not available

        - `close: datetime`

          Session close timestamp with timezone offset

        - `open: datetime`

          Session open timestamp with timezone offset

        - `time_until_close: Optional[str]`

          ISO 8601 duration until session closes. Null if session is not currently open.

        - `time_until_open: Optional[str]`

          ISO 8601 duration until session opens. Null if session has already started or closed.

      - `pre_market: Optional[SessionSchedule]`

        Pre-market session schedule, null if not available

      - `regular: Optional[SessionSchedule]`

        Regular trading session schedule, null if holiday/weekend

    - `status: MarketStatus`

      Market status information

      - `day_type: DayType`

        The type of trading day

        - `"TRADING_DAY"`

        - `"EARLY_CLOSE"`

        - `"HOLIDAY"`

        - `"WEEKEND"`

      - `is_open: bool`

        Whether the market is currently open (real-time)

      - `current_session: Optional[MarketSessionType]`

        Current session type if market is open, null if closed

        - `"pre_market"`

        - `"regular"`

        - `"after_hours"`

    - `timezone: str`

      IANA timezone identifier for the market

    - `today_sessions: TradingSessions`

      Trading session schedules for the requested date with time_until fields