openapi: 3.1.0
info:
  title: Market Metrics
  version: 1.9.1
  description: tastytrade Market Metrics API.
  contact:
    name: tastytrade API support
    email: api.support@tastytrade.com
    url: https://developer.tastytrade.com
paths:
  /market-metrics:
    get:
      description: Returns volatility and liquidity metrics for one or more
        underlyings in a single read-only request. Pass a comma-separated
        `symbols` query list (e.g. `?symbols=AAPL,FB,BRK%2FB`); each underlying
        is returned as a `MarketMetricInfo` object including IV index, IV
        rank/percentile, liquidity ratings, and per-expiration option implied
        volatilities. This is a snapshot endpoint.
      parameters:
        - in: query
          name: symbols
          description: Comma separated list of symbols i.e. ?symbols=AAPL,FB,BRK%2FB
          required: true
          schema:
            type: string
          example: AAPL,FB,BRK/B
      responses:
        "200":
          description: An array of volatility and liquidity metrics, one entry per
            requested symbol.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: "#/components/schemas/MarketMetricInfo"
                    required:
                      - items
                  context:
                    type: string
                    example: /market-metrics
                  pagination:
                    type: object
                    description: Paging metadata, present on paginated list responses.
                    properties:
                      per-page:
                        type: integer
                      page-offset:
                        type: integer
                      item-offset:
                        type: integer
                      total-items:
                        type: integer
                      total-pages:
                        type: integer
                      current-item-count:
                        type: integer
                required:
                  - data
                  - context
        "401":
          description: "Missing or invalid `Authorization` bearer token (tokens expire
            after 15 minutes), or a missing/malformed `User-Agent` header. Send
            `Authorization: Bearer <token>` and a `User-Agent` like
            `my-app/1.0`."
          content:
            application/json:
              schema:
                type: object
                description: Standard tastytrade error envelope. Branch on error.code, not the
                  message text.
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code (see the Error reference).
                      message:
                        type: string
                        description: Human-readable explanation.
                      errors:
                        type: array
                        description: Present for multi-error / validation failures; one entry per
                          problem.
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            domain:
                              type: string
                required:
                  - error
                example:
                  error:
                    code: unauthorized
                    message: No valid access token was provided; access tokens expire after 15
                      minutes.
        "403":
          description: Authenticated, but not authorized to access this resource.
          content:
            application/json:
              schema:
                type: object
                description: Standard tastytrade error envelope. Branch on error.code, not the
                  message text.
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code (see the Error reference).
                      message:
                        type: string
                        description: Human-readable explanation.
                      errors:
                        type: array
                        description: Present for multi-error / validation failures; one entry per
                          problem.
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            domain:
                              type: string
                required:
                  - error
                example:
                  error:
                    code: not_permitted
                    message: User not permitted access
        "422":
          description: Unprocessable content — the request was invalid for this endpoint;
            the reason is returned in `error.message`.
          content:
            application/json:
              schema:
                type: object
                description: Standard tastytrade error envelope. Branch on error.code, not the
                  message text.
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code (see the Error reference).
                      message:
                        type: string
                        description: Human-readable explanation.
                      errors:
                        type: array
                        description: Present for multi-error / validation failures; one entry per
                          problem.
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            domain:
                              type: string
                required:
                  - error
                example:
                  error:
                    code: preflight_check_failure
                    message: One or more preflight checks failed
                    errors:
                      - code: preflight_check_failure
                        message: A specific validation failed for this order.
        "429":
          description: Request rate exceeded reasonable thresholds. Back off exponentially
            and retry.
          content:
            application/json:
              schema:
                type: object
                description: Standard tastytrade error envelope. Branch on error.code, not the
                  message text.
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code (see the Error reference).
                      message:
                        type: string
                        description: Human-readable explanation.
                      errors:
                        type: array
                        description: Present for multi-error / validation failures; one entry per
                          problem.
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            domain:
                              type: string
                required:
                  - error
      operationId: getMarketMetricsIndex
      tags:
        - market-metrics
      x-tt-class: read
      x-money-moving: false
      x-idempotent: true
      x-rate-limit-bucket: read
      summary: Get Market Metrics By Symbols
  /market-metrics/historic-corporate-events/dividends/{symbol}:
    get:
      description: Returns the historical dividend schedule for a single underlying
        identified by the `symbol` path parameter. Each entry reports the date
        the dividend occurred and the per-share amount, useful for reconciling
        payouts or estimating yield.
      parameters:
        - in: path
          name: symbol
          description: Symbol to get dividends data for
          required: true
          schema:
            type: string
          example: AAPL
      responses:
        "200":
          description: An array of historical dividend records for the requested symbol.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: "#/components/schemas/DividendInfo"
                    required:
                      - items
                  context:
                    type: string
                    example: /market-metrics/historic-corporate-events/dividends/{symbol}
                  pagination:
                    type: object
                    description: Paging metadata, present on paginated list responses.
                    properties:
                      per-page:
                        type: integer
                      page-offset:
                        type: integer
                      item-offset:
                        type: integer
                      total-items:
                        type: integer
                      total-pages:
                        type: integer
                      current-item-count:
                        type: integer
                required:
                  - data
                  - context
        "401":
          description: "Missing or invalid `Authorization` bearer token (tokens expire
            after 15 minutes), or a missing/malformed `User-Agent` header. Send
            `Authorization: Bearer <token>` and a `User-Agent` like
            `my-app/1.0`."
          content:
            application/json:
              schema:
                type: object
                description: Standard tastytrade error envelope. Branch on error.code, not the
                  message text.
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code (see the Error reference).
                      message:
                        type: string
                        description: Human-readable explanation.
                      errors:
                        type: array
                        description: Present for multi-error / validation failures; one entry per
                          problem.
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            domain:
                              type: string
                required:
                  - error
                example:
                  error:
                    code: unauthorized
                    message: No valid access token was provided; access tokens expire after 15
                      minutes.
        "403":
          description: Authenticated, but not authorized to access this resource.
          content:
            application/json:
              schema:
                type: object
                description: Standard tastytrade error envelope. Branch on error.code, not the
                  message text.
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code (see the Error reference).
                      message:
                        type: string
                        description: Human-readable explanation.
                      errors:
                        type: array
                        description: Present for multi-error / validation failures; one entry per
                          problem.
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            domain:
                              type: string
                required:
                  - error
                example:
                  error:
                    code: not_permitted
                    message: User not permitted access
        "404":
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                type: object
                description: Standard tastytrade error envelope. Branch on error.code, not the
                  message text.
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code (see the Error reference).
                      message:
                        type: string
                        description: Human-readable explanation.
                      errors:
                        type: array
                        description: Present for multi-error / validation failures; one entry per
                          problem.
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            domain:
                              type: string
                required:
                  - error
        "429":
          description: Request rate exceeded reasonable thresholds. Back off exponentially
            and retry.
          content:
            application/json:
              schema:
                type: object
                description: Standard tastytrade error envelope. Branch on error.code, not the
                  message text.
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code (see the Error reference).
                      message:
                        type: string
                        description: Human-readable explanation.
                      errors:
                        type: array
                        description: Present for multi-error / validation failures; one entry per
                          problem.
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            domain:
                              type: string
                required:
                  - error
      operationId: getMarketMetricsDividendsSymbol
      tags:
        - market-metrics
      x-tt-class: read
      x-money-moving: false
      x-idempotent: true
      x-rate-limit-bucket: read
      summary: Get Historical Dividends
  /market-metrics/historic-corporate-events/earnings-reports/{symbol}:
    get:
      description: Returns historical earnings announcements for a single underlying
        identified by the `symbol` path parameter. Use the required `start-date`
        query parameter to bound the window from that date until now, and the
        optional `end-date` to cap the upper bound. Each entry reports the
        announcement date and reported earnings per share.
      parameters:
        - in: path
          name: symbol
          description: Symbol to get earnings data for
          required: true
          schema:
            type: string
          example: AAPL
        - in: query
          name: start-date
          description: Limits earnings data from start-date until now
          required: true
          schema:
            type: string
            format: date
          example: 2024-01-15
        - in: query
          name: end-date
          description: Limits earnings data from start-date until end-date
          required: false
          schema:
            type: string
            format: date
          example: 2024-01-15
      responses:
        "200":
          description: An array of historical earnings records for the requested symbol
            within the requested date window.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: "#/components/schemas/EarningsInfo"
                    required:
                      - items
                  context:
                    type: string
                    example: /market-metrics/historic-corporate-events/earnings-reports/{symbol}
                  pagination:
                    type: object
                    description: Paging metadata, present on paginated list responses.
                    properties:
                      per-page:
                        type: integer
                      page-offset:
                        type: integer
                      item-offset:
                        type: integer
                      total-items:
                        type: integer
                      total-pages:
                        type: integer
                      current-item-count:
                        type: integer
                required:
                  - data
                  - context
        "401":
          description: "Missing or invalid `Authorization` bearer token (tokens expire
            after 15 minutes), or a missing/malformed `User-Agent` header. Send
            `Authorization: Bearer <token>` and a `User-Agent` like
            `my-app/1.0`."
          content:
            application/json:
              schema:
                type: object
                description: Standard tastytrade error envelope. Branch on error.code, not the
                  message text.
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code (see the Error reference).
                      message:
                        type: string
                        description: Human-readable explanation.
                      errors:
                        type: array
                        description: Present for multi-error / validation failures; one entry per
                          problem.
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            domain:
                              type: string
                required:
                  - error
                example:
                  error:
                    code: unauthorized
                    message: No valid access token was provided; access tokens expire after 15
                      minutes.
        "403":
          description: Authenticated, but not authorized to access this resource.
          content:
            application/json:
              schema:
                type: object
                description: Standard tastytrade error envelope. Branch on error.code, not the
                  message text.
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code (see the Error reference).
                      message:
                        type: string
                        description: Human-readable explanation.
                      errors:
                        type: array
                        description: Present for multi-error / validation failures; one entry per
                          problem.
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            domain:
                              type: string
                required:
                  - error
                example:
                  error:
                    code: not_permitted
                    message: User not permitted access
        "404":
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                type: object
                description: Standard tastytrade error envelope. Branch on error.code, not the
                  message text.
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code (see the Error reference).
                      message:
                        type: string
                        description: Human-readable explanation.
                      errors:
                        type: array
                        description: Present for multi-error / validation failures; one entry per
                          problem.
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            domain:
                              type: string
                required:
                  - error
        "422":
          description: Unprocessable content — the request was invalid for this endpoint.
            Dates must be ISO-8601 (`YYYY-MM-DD`); the reason is returned in
            `error.message`.
          content:
            application/json:
              schema:
                type: object
                description: Standard tastytrade error envelope. Branch on error.code, not the
                  message text.
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code (see the Error reference).
                      message:
                        type: string
                        description: Human-readable explanation.
                      errors:
                        type: array
                        description: Present for multi-error / validation failures; one entry per
                          problem.
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            domain:
                              type: string
                required:
                  - error
                example:
                  error:
                    code: preflight_check_failure
                    message: One or more preflight checks failed
                    errors:
                      - code: preflight_check_failure
                        message: A specific validation failed for this order.
        "429":
          description: Request rate exceeded reasonable thresholds. Back off exponentially
            and retry.
          content:
            application/json:
              schema:
                type: object
                description: Standard tastytrade error envelope. Branch on error.code, not the
                  message text.
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code (see the Error reference).
                      message:
                        type: string
                        description: Human-readable explanation.
                      errors:
                        type: array
                        description: Present for multi-error / validation failures; one entry per
                          problem.
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            domain:
                              type: string
                required:
                  - error
      operationId: getMarketMetricsEarningsSymbol
      tags:
        - market-metrics
      x-tt-class: read
      x-money-moving: false
      x-idempotent: true
      x-rate-limit-bucket: read
      summary: Get Historical Earnings Reports
servers:
  - url: https://api.cert.tastyworks.com
    description: Sandbox
  - url: https://api.tastyworks.com
    description: Production
components:
  schemas:
    DividendInfo:
      type: object
      properties:
        occurred-date:
          description: The date the dividend occurred, in ISO-8601 (`YYYY-MM-DD`) format.
          type: string
          format: date
          example: 2025-02-10
        amount:
          description: The dividend amount paid per share. Decimal value serialized as a
            JSON string (e.g. "150.25").
          type: string
          format: decimal
          example: "0.25"
      description: A single historical dividend record for an underlying — the date
        the dividend occurred and the per-share amount. Returned as an array by
        `GET /market-metrics/historic-corporate-events/dividends/{symbol}`.
    EarningsInfo:
      type: object
      properties:
        occurred-date:
          description: The date of the earnings announcement, in ISO-8601 (`YYYY-MM-DD`)
            format.
          type: string
          format: date
          example: 2025-01-30
        eps:
          description: The reported earnings per share for the announcement. Decimal value
            serialized as a JSON string (e.g. "150.25").
          type: string
          format: decimal
          example: "2.40"
      description: A single historical earnings record for an underlying — the
        announcement date and reported earnings per share. Returned as an array
        by `GET
        /market-metrics/historic-corporate-events/earnings-reports/{symbol}`.
    MarketMetricInfo:
      type: object
      properties:
        symbol:
          description: The underlying symbol these metrics describe, in tastytrade
            symbology.
          type: string
          example: AAPL
        implied-volatility-index:
          description: The implied-volatility index of the underlying. Decimal value
            serialized as a JSON string (e.g. "150.25").
          type: string
          format: decimal
          example: "0.3125"
        implied-volatility-index-5-day-change:
          description: The 5-day change of the underlying's implied-volatility index.
            Decimal value serialized as a JSON string (e.g. "150.25").
          type: string
          format: decimal
          example: "-0.0182"
        implied-volatility-rank:
          description: The implied-volatility rank of the underlying. Decimal value
            serialized as a JSON string (e.g. "150.25").
          type: string
          format: decimal
          example: "0.4567"
        implied-volatility-percentile:
          description: The implied-volatility percentile of the underlying. Decimal value
            serialized as a JSON string (e.g. "150.25").
          type: string
          format: decimal
          example: "0.5210"
        liquidity:
          description: A measure of the underlying's liquidity. Decimal value serialized
            as a JSON string (e.g. "150.25").
          type: string
          format: decimal
          example: "12345.67"
        liquidity-rank:
          description: The liquidity rank of the underlying. Decimal value serialized as a
            JSON string (e.g. "150.25").
          type: string
          format: decimal
          example: "0.8123"
        liquidity-rating:
          description: The liquidity rating of the underlying. Decimal value serialized as
            a JSON string (e.g. "150.25").
          type: string
          format: decimal
          example: "4"
        option-expiration-implied-volatilities:
          description: Per-expiration implied-volatility data for the underlying's option
            chain, one entry per expiration date.
          type: array
          items:
            type: object
            properties:
              expiration-date:
                description: Option expiration date
                type: string
                format: date-time
              settlement-type:
                description: AM or PM settlement
                type: string
              option-chain-type:
                description: Option chain type i.e. Standard or Non-standard.
                type: string
              implied-volatility:
                description: Implied volatility of option expiration Decimal value serialized as
                  a JSON string (e.g. "150.25").
                type: string
                format: decimal
      description: Volatility and liquidity metrics for a single underlying, including
        the underlying's implied-volatility index, IV rank/percentile, liquidity
        ratings, and a list of per-expiration option implied volatilities.
        Returned by `GET /market-metrics`.
x-tastytrade-service:
  serviceName: market-metrics-server
  group: market-metrics
  title: Market Metrics
tags:
  - name: market-metrics
