openapi: 3.0.1
info:
  version: 1.0.0
  title: Authorization Tokens Accounts Short Interest API
  description: 'Use the `oauth` endpoint to generate the secure, time-limited JSON Web Tokens (JWTs) used to authorize access to APIs and components.</br></br>

    To request a token, click Authorize and enter the following credentials:


    * Username - Your Client ID.

    * Password - Your Client Secret.'
servers:
- url: https://www.us-api.morningstar.com/token
  description: PROD US
- url: https://www.emea-api.morningstar.com/token
  description: PROD EMEA
- url: https://www.apac-api.morningstar.com/token
  description: PROD APAC
security:
- BasicAuth: []
tags:
- name: Short Interest
paths:
  /direct-web-services/v1/investments/{id}/equity-short-interest:
    get:
      summary: Get Short Interest view
      parameters:
      - name: id
        in: path
        description: "\nSpecifies the investment to query. \nMorningstar Performance ID is the default identifer for the API. Use the Universe API to retrieve Performance IDs for investments in your entitled universe."
        required: true
        schema:
          type: string
          example: 0P00000046
        examples:
          performanceId:
            summary: Morningstar Performance ID
            value: 0P00000046
          isin:
            summary: ISIN
            value: US0042391096
      - name: idType
        in: query
        description: 'Specifies the type of the value passed in the `id` parameter.

          Morningstar Performance ID is the default identifer for the API. Use the Universe API to retrieve Performance IDs for investments in your entitled universe.'
        schema:
          enum:
          - performanceId
          - isin
          - securityId
          - cusip
          - tradingSymbol
          - fundCode
          - msid
          type: string
          default: performanceId
      - name: baseCurrency
        in: query
        description: Base currency to use for investment lookup. Accepts 3‑character ISO 4217 currency codes.
        schema:
          type: string
        examples:
          baseCurrencyExample1:
            summary: US Dollar
            value: USD
          baseCurrencyExample2:
            summary: Swiss Franc
            value: CHF
      - name: domicile
        in: query
        description: Domicile to use for investment lookup. Accepts 3-character ISO 3166-1 country codes.
        schema:
          type: string
        examples:
          domicileExample1:
            summary: CAN (Canada)
            value: CAN
          domicileExample2:
            summary: JPN (Japan)
            value: JPN
          domicileExample3:
            summary: USE (United States)
            value: USA
      - name: exchangeCountry
        in: query
        description: Exchange country to use for investment lookup. Accepts 3-character ISO 3166-1 country codes.
        schema:
          type: string
        examples:
          exchangeCountryExample1:
            summary: CAN (Canada)
            value: CAN
          exchangeCountryExample2:
            summary: JPN (Japan)
            value: JPN
          exchangeCountryExample3:
            summary: USA (USA)
            value: USA
      - name: exchangeId
        in: query
        description: Exchange identifier to use for investment lookup.
        schema:
          type: string
          externalDocs:
            description: List of exchange IDs.
            url: https://developer.morningstar.com/content/hidden-from-navigation/DwsIdLookUpExchangeIds.xlsx
        examples:
          exchangeIdExample1:
            summary: NASDAQ - ALL Markets (NAS)
            value: EX$$$$XNAS
          exchangeIdExample2:
            summary: London Stock Exchange (LSE)
            value: EX$$$$XLON
      - name: startDate
        in: query
        schema:
          type: string
          format: yyyy-MM-dd
        description: Time series start date. Accepts `yyyy-MM-dd`.
        examples:
          startDateExample1:
            summary: Example 1
            value: '2025-06-01'
          startDateExample2:
            summary: Example 2
            value: '2025-06-30'
      - name: endDate
        in: query
        schema:
          type: string
          format: yyyy-MM-dd
        description: Time series end date. Accepts `yyyy-MM-dd`.
        examples:
          endDateExample1:
            summary: Example 1
            value: '2025-12-01'
          endDateExample2:
            summary: Example 2
            value: '2025-12-31'
      description: Time series data supported.
      operationId: getEquityShortInterestDataset
      tags:
      - Short Interest
      responses:
        '200':
          $ref: '#/components/responses/ResponseEquityShortInterest'
        '400':
          $ref: '#/components/responses/ResponseBadRequest'
        '500':
          $ref: '#/components/responses/ResponseInternalServerError'
      x-cpqId: 931
components:
  schemas:
    OutputMetadataMessages:
      type: object
      properties:
        type:
          type: string
          nullable: true
        code:
          type: string
          nullable: true
        investments:
          type: array
          items:
            $ref: '#/components/schemas/OutputInvalidInvestments'
          nullable: true
        message:
          type: string
          nullable: true
      additionalProperties: false
      title: OutputMetadataMessages
    OutputShortInterest:
      type: object
      properties:
        settlementDate:
          type: string
          description: Date when the short interest data becomes effective. It is the date specified for delivery of securities between securities firms. This date marks the official date for change of ownership and is used for accounting for long or short positions.
          nullable: true
        averageDailyVolume:
          type: integer
          description: The number of shares of stock traded each day; averaged over a 1 month period through the settlement date.
          format: int64
          nullable: true
        daysToCover:
          type: number
          description: Calculated as the aggregate short interest for the month divided by the average daily share volume traded between short interest settlement dates. Also known as 'Short Interest Ratio'. Days To Cover = Short Interest / Average Daily Volume
          format: double
          nullable: true
        daysToCoverPercentageChanged:
          type: number
          description: Calculated as the aggregate short interest for the month divided by the average daily share volume traded between short interest settlement dates. Also known as Short Interest Ratio. Days To Cover = Short Interest / Average Daily Volume
          format: double
          nullable: true
        percentageChanged:
          type: number
          description: The percentage that the Short Interest shares have changed compared to the previous period. Percentage Changed = [(Current Short Interest / Previous Short Interest) - 1] * 100
          format: double
          nullable: true
        percentageOfFloat:
          type: number
          description: Percentage of Short Interest shares to Float shares outstanding. Percentage of Float % = Short Interest / Float Shares * 100
          format: double
          nullable: true
        percentageOfSharesOutstanding:
          type: number
          description: Percentage of Short Interest shares to total shares outstanding. Percentage of Shares Outstanding % = Short Interest / Total Shares Outstanding * 100
          format: double
          nullable: true
        shortInterestValue:
          type: integer
          description: The total number of shares of a security that have been sold short by customers and securities firms that have not been repurchased to settle outstanding short positions in the market; the net short positions outstanding in the stock as of the settlement date.
          format: int64
          nullable: true
      additionalProperties: false
      title: OutputShortInterest
    OutputErrorDetails:
      type: object
      properties:
        statusCode:
          type: integer
          description: Status Code
          format: int32
        errorCode:
          type: string
          description: Custom error code
          nullable: true
        message:
          type: string
          description: Message
          nullable: true
        requestId:
          type: string
          description: RequestId
          nullable: true
      additionalProperties: false
      description: Error details
      title: OutputErrorDetails
    OutputIdentifiers:
      type: object
      properties:
        performanceId:
          type: string
          nullable: true
        securityId:
          type: string
          nullable: true
        cusip:
          type: string
          nullable: true
        isin:
          type: string
          nullable: true
        sedol:
          type: string
          nullable: true
        tradingSymbol:
          type: string
          nullable: true
        fundCode:
          type: string
          nullable: true
        msid:
          type: string
          nullable: true
        ticker:
          type: string
          nullable: true
      additionalProperties: false
      title: OutputIdentifiers
    OutputInvalidInvestments:
      type: object
      properties:
        id:
          type: string
          nullable: true
        idType:
          type: string
          nullable: true
        status:
          type: string
          nullable: true
        datapointId:
          type: array
          items:
            type: string
          nullable: true
        errorCode:
          type: string
          nullable: true
        performanceId:
          type: string
          description: Performance ID (if not passed in request).
          nullable: true
        companyId:
          type: string
          description: Company ID (if not passed in request).
          nullable: true
        baseCurrency:
          type: string
          description: Input base currency used to look up Investment identifier
          nullable: true
        domicile:
          type: string
          description: Input domicile used to look up Investment identifier.
          nullable: true
        exchangeCountry:
          type: string
          description: Input exchange country used to look up Investment identifier.
          nullable: true
        exchangeId:
          type: string
          description: Input exchange id used to look up Investment identifier.
          nullable: true
      additionalProperties: false
      title: OutputInvalidInvestments
    OutputMetadata:
      type: object
      properties:
        requestId:
          type: string
          nullable: true
        time:
          type: string
          format: date-time
          readOnly: true
        portfolioDate:
          type: string
          nullable: true
        portfolioCurrency:
          type: string
          nullable: true
        messages:
          type: array
          items:
            $ref: '#/components/schemas/OutputMetadataMessages'
          nullable: true
      additionalProperties: false
      title: OutputMetadata
  responses:
    ResponseBadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OutputErrorDetails'
    ResponseEquityShortInterest:
      description: OK
      content:
        application/json:
          schema:
            type: object
            properties:
              shortInterest:
                $ref: '#/components/schemas/OutputShortInterest'
              identifiers:
                $ref: '#/components/schemas/OutputIdentifiers'
              metadata:
                $ref: '#/components/schemas/OutputMetadata'
    ResponseInternalServerError:
      description: Internal Server
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OutputErrorDetails'
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic