Clearstreet8e71 Calendar API

openapi: 3.2.0
info:
  title: Clear Street Trading Calendar API
  description: A unified, secure, and high-performance RESTful API for all client interactions with the Active trading platform.
  contact:
    name: Clear Street API Support
    url: https://clearstreet.io/contact
    email: concierge@clearstreet.com
  license:
    name: Proprietary
    url: https://clearstreet.io/terms
  version: 2025-10-31
servers:
- url: https://api.clearstreet.com
  description: Clear Street API
- url: https://api-dev.clearstreet.com
  description: Clear Street Development API
- url: http://localhost:5001
  description: Clear Street Local API
security:
- BearerAuth: []
tags:
- name: Calendar
  description: Access clocks and financial calendars for market sessions and events.
paths:
  /v1/calendars/economic-events:
    get:
      tags:
      - Calendar
      summary: Get Economic Calendar Events
      description: 'Retrieves macroeconomic calendar events (e.g. CPI, jobs reports, central

        bank rate decisions), optionally filtered by country, impact, and event

        time range.


        Absent a `timestamp` lower bound, results default to events from the

        start of the previous trading day (America/New_York); absent an upper

        bound, results default through 7 days from today (America/New_York).'
      operationId: get_economic_events_calendar
      parameters:
      - name: country
        in: query
        description: Comma-separated ISO 3166-1 alpha-2 country codes (or `EU`) to filter by. Defaults to `US` when omitted.
        required: false
        schema:
          type: string
      - name: impact
        in: query
        description: Comma-separated impact levels to filter by.
        required: false
        schema:
          type: array
          items:
            type: string
            description: Market impact of an economic calendar event.
            enum:
            - NONE
            - LOW
            - MEDIUM
            - HIGH
        style: form
        explode: false
      - name: timestamp.gt
        in: query
        description: Return only rows where `timestamp` is strictly after the given value. A bare `YYYY-MM-DD` date expands to the end of that day (UTC), so this matches from the start of the following day. See [Range filters](https://docs.clearstreet.com/guides/api-fundamentals#range-filters) for accepted formats, bare-date expansion, and combining bounds. Returns 400 if the resulting range is inverted.
        required: false
        schema:
          type: string
      - name: timestamp.gte
        in: query
        description: Return only rows where `timestamp` is on or after the given value. A bare `YYYY-MM-DD` date expands to the start of that day (UTC). See [Range filters](https://docs.clearstreet.com/guides/api-fundamentals#range-filters) for accepted formats, bare-date expansion, and combining bounds. Returns 400 if the resulting range is inverted.
        required: false
        schema:
          type: string
      - name: timestamp.lt
        in: query
        description: Return only rows where `timestamp` is strictly before the given value. A bare `YYYY-MM-DD` date expands to the start of that day (UTC). See [Range filters](https://docs.clearstreet.com/guides/api-fundamentals#range-filters) for accepted formats, bare-date expansion, and combining bounds. Returns 400 if the resulting range is inverted.
        required: false
        schema:
          type: string
      - name: timestamp.lte
        in: query
        description: Return only rows where `timestamp` is on or before the given value. A bare `YYYY-MM-DD` date expands to the end of that day (UTC), so this matches through the end of that day. See [Range filters](https://docs.clearstreet.com/guides/api-fundamentals#range-filters) for accepted formats, bare-date expansion, and combining bounds. Returns 400 if the resulting range is inverted.
        required: false
        schema:
          type: string
      - name: page_size
        in: query
        description: The number of items to return per page. Only used when page_token is not provided.
        required: false
        schema:
          type: integer
          format: int64
          default: 1000
          maximum: 10000
          minimum: 1
      - name: page_token
        in: query
        description: Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored.
        required: false
        schema:
          type: string
          format: byte
          description: Base64URL-encoded pagination token
        example: eyJvZmZzZXQiOjEwMCwibGltaXQiOjEwMH0=
      responses:
        '200':
          description: Economic calendar events
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BaseResponse'
                - type: object
                  required:
                  - data
                  properties:
                    data:
                      $ref: '#/components/schemas/EconomicEventList'
                type: object
              examples:
                EconomicEvents:
                  summary: A page of upcoming economic events
                  value:
                    data:
                    - actual: null
                      change: null
                      change_percentage: null
                      country: US
                      currency: USD
                      estimate: '0.30'
                      impact: HIGH
                      name: CPI m/m
                      previous: '0.20'
                      timestamp: 2025-11-05 13:30:00+00:00
                      unit: '%'
                    error: null
                    metadata:
                      request_id: 0f1a2b3c-4d5e-6f78-9012-3a4b5c6d7e8f
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/calendars/market-hours:
    get:
      tags:
      - Calendar
      summary: Get Market Hours Calendar
      description: 'Retrieves comprehensive trading hours including pre-market, regular, and after-hours sessions.

        Returns market status, session times, and next session schedules.'
      operationId: get_market_hours_calendar
      parameters:
      - name: date
        in: query
        description: The date to query market hours for (YYYY-MM-DD). Defaults to today.
        required: false
        schema:
          type: string
        example: 2025-10-15
      - name: market
        in: query
        description: Market type to query (us_equities, us_options). If omitted, returns all markets.
        required: false
        schema:
          type: string
          description: Market type for market hours calendar endpoint
          enum:
          - us_equities
          - us_options
        example: us_equities
      responses:
        '200':
          description: Market hours calendar
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BaseResponse'
                - type: object
                  required:
                  - data
                  properties:
                    data:
                      $ref: '#/components/schemas/MarketHoursDetailList'
                type: object
              examples:
                EarlyClose:
                  summary: Market hours for an early close day (day after Thanksgiving)
                  value:
                    data:
                    - current_time: 2025-11-28 11:00:00-05:00
                      date: 2025-11-28
                      market: us_equities
                      market_name: US Equities
                      next_sessions:
                        after_hours:
                          close: 2025-12-01 20:00:00-05:00
                          open: 2025-12-01 16:00:00-05:00
                        pre_market:
                          close: 2025-12-01 09:30:00-05:00
                          open: 2025-12-01 04:00:00-05:00
                        regular:
                          close: 2025-12-01 16:00:00-05:00
                          open: 2025-12-01 09: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-28 09:30:00-05:00
                          open: 2025-11-28 04:00:00-05:00
                        regular:
                          close: 2025-11-28 13:00:00-05:00
                          open: 2025-11-28 09:30:00-05:00
                          time_until_close: PT2H
                    error: null
                    metadata:
                      request_id: 3d4e5f6a-7b8c-9d0e-1f2a-3b4c5d6e7f8a
                Holiday:
                  summary: Market hours for a holiday (Christmas)
                  value:
                    data:
                    - current_time: 2025-12-25 10:00:00-05:00
                      date: 2025-12-25
                      market: us_equities
                      market_name: US Equities
                      next_sessions:
                        after_hours:
                          close: 2025-12-26 20:00:00-05:00
                          open: 2025-12-26 16:00:00-05:00
                        pre_market:
                          close: 2025-12-26 09:30:00-05:00
                          open: 2025-12-26 04:00:00-05:00
                        regular:
                          close: 2025-12-26 16:00:00-05:00
                          open: 2025-12-26 09:30:00-05:00
                      status:
                        day_type: HOLIDAY
                        is_open: false
                      timezone: America/New_York
                      today_sessions: {}
                    error: null
                    metadata:
                      request_id: 2c3d4e5f-6a7b-8c9d-0e1f-2a3b4c5d6e7f
                RegularTradingDay:
                  summary: Market hours for a regular trading day
                  value:
                    data:
                    - current_time: 2025-10-15 14:30:45-04:00
                      date: 2025-10-15
                      market: us_equities
                      market_name: US Equities
                      next_sessions:
                        after_hours:
                          close: 2025-10-16 20:00:00-04:00
                          open: 2025-10-16 16:00:00-04:00
                        pre_market:
                          close: 2025-10-16 09:30:00-04:00
                          open: 2025-10-16 04:00:00-04:00
                        regular:
                          close: 2025-10-16 16:00:00-04:00
                          open: 2025-10-16 09:30:00-04:00
                      status:
                        current_session: regular
                        day_type: TRADING_DAY
                        is_open: true
                      timezone: America/New_York
                      today_sessions:
                        after_hours:
                          close: 2025-10-15 20:00:00-04:00
                          open: 2025-10-15 16:00:00-04:00
                          time_until_open: PT1H29M15S
                        pre_market:
                          close: 2025-10-15 09:30:00-04:00
                          open: 2025-10-15 04:00:00-04:00
                        regular:
                          close: 2025-10-15 16:00:00-04:00
                          open: 2025-10-15 09:30:00-04:00
                          time_until_close: PT1H29M15S
                    error: null
                    metadata:
                      request_id: 1b2c3d4e-5f6a-7b8c-9d0e-1f2a3b4c5d6e
                Weekend:
                  summary: Market hours for a weekend day
                  value:
                    data:
                    - current_time: 2025-10-18 12:00:00-04:00
                      date: 2025-10-18
                      market: us_equities
                      market_name: US Equities
                      next_sessions:
                        after_hours:
                          close: 2025-10-20 20:00:00-04:00
                          open: 2025-10-20 16:00:00-04:00
                        pre_market:
                          close: 2025-10-20 09:30:00-04:00
                          open: 2025-10-20 04:00:00-04:00
                        regular:
                          close: 2025-10-20 16:00:00-04:00
                          open: 2025-10-20 09:30:00-04:00
                      status:
                        day_type: WEEKEND
                        is_open: false
                      timezone: America/New_York
                      today_sessions: {}
                    error: null
                    metadata:
                      request_id: 4e5f6a7b-8c9d-0e1f-2a3b-4c5d6e7f8a9b
  /v1/clock:
    get:
      tags:
      - Calendar
      summary: Get Clock
      description: Returns the current server time in UTC.
      operationId: get_clock
      responses:
        '200':
          description: Current server time
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BaseResponse'
                - type: object
                  required:
                  - data
                  properties:
                    data:
                      $ref: '#/components/schemas/ClockDetail'
                type: object
              examples:
                Current time:
                  summary: Current server time
                  value:
                    data:
                      clock: 2025-03-01 03:35:00+00:00
                    error: null
                    metadata:
                      request_id: 1b2c3d4e-5f6a-7b8c-9d0e-1f2a3b4c5d6e
components:
  schemas:
    MarketHoursDetail:
      type: object
      description: Comprehensive market hours information for a specific market and date
      required:
      - market
      - market_name
      - date
      - timezone
      - current_time
      - status
      - today_sessions
      - next_sessions
      properties:
        current_time:
          type: string
          format: date-time
          description: Current time in market timezone with offset
          example: 2025-10-15 14:30:00-04:00
        date:
          type: string
          format: date
          description: The date for which market hours are provided
          example: 2025-10-15
        market:
          $ref: '#/components/schemas/MarketType'
          description: Market type identifier
        market_name:
          type: string
          description: Human-readable market name
          example: US Equities
        next_sessions:
          $ref: '#/components/schemas/TradingSessions'
          description: Next trading day's session schedules (without time_until fields)
        status:
          $ref: '#/components/schemas/MarketStatus'
          description: Market status information
        timezone:
          type: string
          description: IANA timezone identifier for the market
          example: America/New_York
        today_sessions:
          $ref: '#/components/schemas/TradingSessions'
          description: Trading session schedules for the requested date with time_until fields
      example:
        current_time: 2025-10-15 14:30:00-04:00
        date: 2025-10-15
        market: us_equities
        market_name: US Equities
        next_sessions:
          after_hours:
            close: 2025-10-16 20:00:00-04:00
            open: 2025-10-16 16:00:00-04:00
          overnight:
            close: 2025-10-16 04:00:00-04:00
            open: 2025-10-15 20:00:00-04:00
          pre_market:
            close: 2025-10-16 09:30:00-04:00
            open: 2025-10-16 04:00:00-04:00
          regular:
            close: 2025-10-16 16:00:00-04:00
            open: 2025-10-16 09:30:00-04:00
        status:
          current_session: regular
          day_type: TRADING_DAY
          is_open: true
        timezone: America/New_York
        today_sessions:
          after_hours:
            close: 2025-10-15 20:00:00-04:00
            open: 2025-10-15 16:00:00-04:00
            time_until_open: PT1H30M
          overnight:
            close: 2025-10-15 04:00:00-04:00
            open: 2025-10-14 20:00:00-04:00
          pre_market:
            close: 2025-10-15 09:30:00-04:00
            open: 2025-10-15 04:00:00-04:00
          regular:
            close: 2025-10-15 16:00:00-04:00
            open: 2025-10-15 09:30:00-04:00
            time_until_close: PT1H30M
    SessionSchedule:
      type: object
      description: Session schedule with open and close timestamps
      required:
      - open
      - close
      properties:
        close:
          type: string
          format: date-time
          description: Session close timestamp with timezone offset
          example: 2025-10-15 16:00:00-04:00
        open:
          type: string
          format: date-time
          description: Session open timestamp with timezone offset
          example: 2025-10-15 09:30:00-04:00
        time_until_close:
          type:
          - string
          - 'null'
          format: duration
          description: 'ISO 8601 duration until session closes. Null if session is not currently open.

            When a null/undefined value is observed, it indicates it does not apply.'
          example: PT1H30M
        time_until_open:
          type:
          - string
          - 'null'
          format: duration
          description: 'ISO 8601 duration until session opens. Null if session has already started or closed.

            When a null/undefined value is observed, it indicates it does not apply.'
          example: PT2H30M
      example:
        close: 2025-10-15 16:00:00-04:00
        open: 2025-10-15 09:30:00-04:00
        time_until_close: PT1H30M
        time_until_open: null
    DayType:
      type: string
      description: Day type for market hours - indicates the type of trading day
      enum:
      - TRADING_DAY
      - EARLY_CLOSE
      - HOLIDAY
      - WEEKEND
    MarketHoursDetailList:
      type: array
      items:
        $ref: '#/components/schemas/MarketHoursDetail'
    ErrorDetails:
      type: array
      items:
        type: object
        additionalProperties: true
    EconomicEventList:
      type: array
      items:
        $ref: '#/components/schemas/EconomicEvent'
    TradingSessions:
      type: object
      description: Trading sessions for a market day with full timestamps
      properties:
        after_hours:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/SessionSchedule'
            description: 'After-hours session schedule, null if not available

              When a null/undefined value is observed, it indicates it does not apply.'
        overnight:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/SessionSchedule'
            description: 'Overnight session schedule (prior evening through early morning), null if not available

              When a null/undefined value is observed, it indicates it does not apply.'
        pre_market:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/SessionSchedule'
            description: 'Pre-market session schedule, null if not available

              When a null/undefined value is observed, it indicates it does not apply.'
        regular:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/SessionSchedule'
            description: 'Regular trading session schedule, null if holiday/weekend

              When a null/undefined value is observed, it indicates it does not apply.'
      example:
        after_hours:
          close: 2025-10-15 20:00:00-04:00
          open: 2025-10-15 16:00:00-04:00
        overnight:
          close: 2025-10-15 04:00:00-04:00
          open: 2025-10-14 20:00:00-04:00
        pre_market:
          close: 2025-10-15 09:30:00-04:00
          open: 2025-10-15 04:00:00-04:00
        regular:
          close: 2025-10-15 16:00:00-04:00
          open: 2025-10-15 09:30:00-04:00
    EconomicEventImpact:
      type: string
      description: Market impact of an economic calendar event.
      enum:
      - NONE
      - LOW
      - MEDIUM
      - HIGH
    ResponseMetadata:
      type: object
      description: 'Metadata for the response. This will always contain a request ID which can be used to identify

        the request to Clear Street for tracing, and optionally may include pagination data.'
      required:
      - request_id
      properties:
        next_page_token:
          oneOf:
          - type: 'null'
          - type: string
            format: byte
            description: Base64URL-encoded pagination token
          description: 'A token that can be used to retrieve the next page of results, if any.

            The token contains opaque pagination state.

            Filtering and sorting parameters must be provided with each request.'
        page_number:
          type:
          - integer
          - 'null'
          format: int32
          description: Pagination. Included if this was a GET (list) response
          example: 1
          minimum: 0
        previous_page_token:
          oneOf:
          - type: 'null'
          - type: string
            format: byte
            description: Base64URL-encoded pagination token
          description: 'A token that can be used to retrieve the previous page of results, if any.

            The token contains opaque pagination state.

            Filtering and sorting parameters must be provided with each request.'
        request_id:
          type: string
          description: A unique ID for this request, generated upon ingestion of the request.
        total_items:
          type:
          - integer
          - 'null'
          format: int64
          description: Total number of items available (not just in this page).
          example: 42
          minimum: 0
        total_pages:
          type:
          - integer
          - 'null'
          format: int32
          description: Total number of pages available.
          example: 5
          minimum: 0
    MarketStatus:
      type: object
      description: Market status information
      required:
      - day_type
      - is_open
      properties:
        current_session:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/MarketSessionType'
            description: 'Current session type if market is open, null if closed

              When a null/undefined value is observed, it indicates it does not apply.'
        day_type:
          $ref: '#/components/schemas/DayType'
          description: The type of trading day
        is_open:
          type: boolean
          description: Whether the market is currently open (real-time)
          example: true
      example:
        current_session: regular
        day_type: TRADING_DAY
        is_open: true
    ClockDetail:
      type: object
      description: Current server time and market clock information
      required:
      - clock
      properties:
        clock:
          type: string
          format: date-time
          description: Current server time in UTC
          example: 2025-03-01 03:35:00+00:00
      example:
        clock: 2025-03-01 03:35:00+00:00
    MarketType:
      type: string
      description: Market type for market hours calendar endpoint
      enum:
      - us_equities
      - us_options
    ApiError:
      type: object
      description: A direct mapping of tonic::Status, for use in HTTP responses.
      required:
      - code
      - message
      properties:
        code:
          type: integer
          format: int32
          description: 'The error code is used to identify the nature of the error. It corresponds

            to an HTTP status code.'
          example: 400
          minimum: 0
        details:
          $ref: '#/components/schemas/ErrorDetails'
          description: 'Additional error details, if any. This can include structured information

            such as field violations or error metadata.'
        message:
          type: string
          description: A human-readable message providing more details about the error.
          example: Order quantity must be greater than zero
    BaseResponse:
      type: object
      required:
      - metadata
      properties:
        error:
          oneOf:
          - oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/ApiError'
              description: Structured error details when the request is unsuccessful.
        metadata:
          $ref: '#/components/schemas/ResponseMetadata'
          description: Response metadata, including the request ID and optional pagination info.
    MarketSessionType:
      type: string
      description: Session type for market hours
      enum:
      - overnight
      - pre_market
      - regular
      - after_hours
    EconomicEventUnit:
      type: string
      description: 'Unit of an economic calendar event''s numeric values. Known values: `%`, `K` (thousand), `M` (million), `B` (billion), `T` (trillion), `Points`. Any other provider-supplied string passes through unchanged.'
      examples:
      - '%'
    EconomicEvent:
      type: object
      description: 'A single economic calendar event.


        Coverage spans roughly 365 days back to 90 days forward. `estimate` and

        `actual` are frequently absent for minor releases, speeches, and holidays.

        The calendar refreshes daily (around 7am ET), so `actual` can trail the

        real-world print by up to a day; a null `actual` before the print is

        expected, not missing data.'
      required:
      - timestamp
      - name
      - country
      properties:
        actual:
          type:
          - string
          - 'null'
          description: 'Actual reported value. Null before the print, or if the provider never

            reports one for this event.

            When a null/undefined value is observed, it indicates that there is no available data.'
          example: '0.30'
        change:
          type:
          - string
          - 'null'
          description: 'Change from the previous value.

            When a null/undefined value is observed, it indicates that there is no available data.'
          example: '0.10'
        change_percentage:
          type:
          - string
          - 'null'
          description: 'Change from the previous value, as a percentage.

            When a null/undefined value is observed, it indicates that there is no available data.'
          example: '50.00'
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code, or `EU`.
          example: US
        currency:
          type:
          - string
          - 'null'
          description: 'Currency associated with the event, if applicable.

            When a null/undefined value is observed, it indicates that there is no available data.'
          example: USD
        estimate:
          type:
          - string
          - 'null'
          description: 'Analyst-estimated value.

            When a null/undefined value is observed, it indicates that there is no available data.'
          example: '0.30'
        impact:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/EconomicEventImpact'
            description: 'Expected market impact, if known.

              When a null/undefined value is observed, it indicates that there is no available data.'
        name:
          type: string
          description: Event name as reported by the provider.
          example: CPI m/m
        previous:
          type:
          - string
          - 'null'
          description: 'Previous period''s reported value.

            When a null/undefined value is observed, it indicates that there is no available data.'
          example: '0.20'
        timestamp:
          type: string
          format: date-time
          description: UTC instant of the event.
          example: 2026-09-25 12:30:00+00:00
        unit:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/EconomicEventUnit'
            description: 'Unit of the numeric value fields, if known.

              When a null/undefined value is observed, it indicates that there is no available data.'
      example:
        actual: null
        change: null
        change_percentage: null
        country: US
        currency: USD
        estimate: '0.30'
        impact: HIGH
        name: CPI m/m
        previous: '0.20'
        timestamp: 2026-09-25 12:30:00+00:00
        unit: '%'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT