Polygon Us Stocks Reference API

openapi: 3.2.0
info:
  description: The future of fintech.
  title: Polygon Us Stocks Reference API
  version: 1.0.0
servers:
- description: Polygon Platform API
  url: https://api.polygon.io
- description: Polygon Platform API (Staging)
  url: https://api.staging.polygon.io
security:
- apiKey: []
tags:
- name: us_stocks_reference
paths:
  /stocks/v1/dividends:
    get:
      description: Contains historical dividend payment records for US stocks with split-adjusted amounts and historical adjustment factors for price normalization.
      operationId: get_stocks_v1_dividends
      parameters:
      - description: Stock symbol for the company issuing the dividend
        in: query
        name: ticker
        schema:
          type: string
      - description: Filter equal to any of the values. Multiple values can be specified by using a comma separated list.
        in: query
        name: ticker.any_of
        schema:
          type: string
      - description: Filter greater than the value.
        in: query
        name: ticker.gt
        schema:
          type: string
      - description: Filter greater than or equal to the value.
        in: query
        name: ticker.gte
        schema:
          type: string
      - description: Filter less than the value.
        in: query
        name: ticker.lt
        schema:
          type: string
      - description: Filter less than or equal to the value.
        in: query
        name: ticker.lte
        schema:
          type: string
      - description: Date when the stock begins trading without the dividend value Value must be formatted 'yyyy-mm-dd'.
        in: query
        name: ex_dividend_date
        schema:
          type: string
      - description: Filter greater than the value. Value must be formatted 'yyyy-mm-dd'.
        in: query
        name: ex_dividend_date.gt
        schema:
          type: string
      - description: Filter greater than or equal to the value. Value must be formatted 'yyyy-mm-dd'.
        in: query
        name: ex_dividend_date.gte
        schema:
          type: string
      - description: Filter less than the value. Value must be formatted 'yyyy-mm-dd'.
        in: query
        name: ex_dividend_date.lt
        schema:
          type: string
      - description: Filter less than or equal to the value. Value must be formatted 'yyyy-mm-dd'.
        in: query
        name: ex_dividend_date.lte
        schema:
          type: string
      - description: How many times per year this dividend is expected to occur. A value of 0 means the distribution is non-recurring or irregular (e.g., special, supplemental, or a one-off dividend). Other possible values include 1 (annual), 2 (semi-annual), 3 (trimester), 4 (quarterly), 12 (monthly), 24 (bi-monthly), 52 (weekly), 104 (bi-weekly), and 365 (daily) depending on the issuer's declared or inferred payout cadence. Value must be an integer.
        in: query
        name: frequency
        schema:
          format: int64
          type: integer
      - description: Filter greater than the value. Value must be an integer.
        in: query
        name: frequency.gt
        schema:
          format: int64
          type: integer
      - description: Filter greater than or equal to the value. Value must be an integer.
        in: query
        name: frequency.gte
        schema:
          format: int64
          type: integer
      - description: Filter less than the value. Value must be an integer.
        in: query
        name: frequency.lt
        schema:
          format: int64
          type: integer
      - description: Filter less than or equal to the value. Value must be an integer.
        in: query
        name: frequency.lte
        schema:
          format: int64
          type: integer
      - description: 'Classification describing the nature of this dividend''s recurrence pattern: recurring (paid on a regular schedule), special (one-time or commemorative), supplemental (extra beyond the regular schedule), irregular (unpredictable or non-recurring), unknown (cannot be classified from available data)'
        in: query
        name: distribution_type
        schema:
          enum:
          - recurring
          - special
          - supplemental
          - irregular
          - unknown
          type: string
      - description: Filter equal to any of the values. Multiple values can be specified by using a comma separated list.
        in: query
        name: distribution_type.any_of
        schema:
          enum:
          - recurring
          - special
          - supplemental
          - irregular
          - unknown
          type: string
      - description: Limit the maximum number of results returned. Defaults to '100' if not specified. The maximum allowed limit is '5000'.
        in: query
        name: limit
        schema:
          default: 100
          maximum: 5000
          minimum: 1
          type: integer
      - description: A comma separated list of sort columns. For each column, append '.asc' or '.desc' to specify the sort direction. The sort column defaults to 'ticker' if not specified. The sort order defaults to 'asc' if not specified.
        in: query
        name: sort
        schema:
          default: ticker.asc
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                request_id: 1
                results:
                - cash_amount: 0.26
                  currency: USD
                  declaration_date: '2025-07-31'
                  distribution_type: recurring
                  ex_dividend_date: '2025-08-11'
                  frequency: 4
                  historical_adjustment_factor: 0.997899
                  id: Ed2c9da60abda1e3f0e99a43f6465863c137b671e1f5cd3f833d1fcb4f4eb27fe
                  pay_date: '2025-08-14'
                  record_date: '2025-08-11'
                  split_adjusted_cash_amount: 0.26
                  ticker: AAPL
                status: OK
              schema:
                properties:
                  next_url:
                    description: If present, this value can be used to fetch the next page.
                    type: string
                  request_id:
                    description: A request id assigned by the server.
                    type: string
                  results:
                    description: The results for this request.
                    items:
                      properties:
                        cash_amount:
                          description: Original dividend amount per share in the specified currency
                          format: double
                          type: number
                        currency:
                          description: Currency code for the dividend payment (e.g., USD, CAD)
                          type: string
                        declaration_date:
                          description: Date when the company officially announced the dividend
                          format: date
                          type: string
                        distribution_type:
                          description: 'Classification describing the nature of this dividend''s recurrence pattern: recurring (paid on a regular schedule), special (one-time or commemorative), supplemental (extra beyond the regular schedule), irregular (unpredictable or non-recurring), unknown (cannot be classified from available data)'
                          type: string
                        ex_dividend_date:
                          description: Date when the stock begins trading without the dividend value
                          format: date
                          type: string
                        frequency:
                          description: How many times per year this dividend is expected to occur. A value of 0 means the distribution is non-recurring or irregular (e.g., special, supplemental, or a one-off dividend). Other possible values include 1 (annual), 2 (semi-annual), 3 (trimester), 4 (quarterly), 12 (monthly), 24 (bi-monthly), 52 (weekly), 104 (bi-weekly), and 365 (daily) depending on the issuer's declared or inferred payout cadence.
                          format: int64
                          type: integer
                        historical_adjustment_factor:
                          description: 'Cumulative adjustment factor used to offset dividend effects on historical prices. To adjust a historical price for dividends: for a price on date D, find the first dividend whose `ex_dividend_date` is after date D and multiply the price by that dividend''s `historical_adjustment_factor`.'
                          format: double
                          type: number
                        id:
                          description: Unique identifier for each dividend record
                          type: string
                        pay_date:
                          description: Date when the dividend payment is distributed to shareholders
                          format: date
                          type: string
                        record_date:
                          description: Date when shareholders must be on record to be eligible for the dividend payment
                          format: date
                          type: string
                        split_adjusted_cash_amount:
                          description: Dividend amount adjusted for stock splits that occurred after the dividend was paid, expressed on a current share basis
                          format: double
                          type: number
                        ticker:
                          description: Stock symbol for the company issuing the dividend
                          type: string
                      required:
                      - distribution_type
                      type: object
                    type: array
                  status:
                    description: The status of this request's response.
                    enum:
                    - OK
                    type: string
                required:
                - status
                - request_id
                - results
                type: object
          description: A list of results.
        '400':
          content:
            application/json:
              schema:
                properties:
                  error:
                    description: A message describing the source of the error.
                    type: string
                  request_id:
                    description: A request id assigned by the server.
                    type: string
                  status:
                    description: The status of this request's response.
                    enum:
                    - ERROR
                    type: string
                required:
                - status
                - request_id
                - error
                type: object
          description: An error message.
      tags:
      - us_stocks_reference
  /stocks/v1/splits:
    get:
      description: Contains historical stock split and reverse split events for US equities with historical adjustment factors for price normalization.
      operationId: get_stocks_v1_splits
      parameters:
      - description: Stock symbol for the company that executed the split
        in: query
        name: ticker
        schema:
          type: string
      - description: Filter equal to any of the values. Multiple values can be specified by using a comma separated list.
        in: query
        name: ticker.any_of
        schema:
          type: string
      - description: Filter greater than the value.
        in: query
        name: ticker.gt
        schema:
          type: string
      - description: Filter greater than or equal to the value.
        in: query
        name: ticker.gte
        schema:
          type: string
      - description: Filter less than the value.
        in: query
        name: ticker.lt
        schema:
          type: string
      - description: Filter less than or equal to the value.
        in: query
        name: ticker.lte
        schema:
          type: string
      - description: Date when the stock split takes effect. The adjustment is applied overnight. On the prior trading day, the post-market session is the last session that shows pre-split prices. On the execution date, all trading is already adjusted for the split. This includes the pre-market session. Value must be formatted 'yyyy-mm-dd'.
        in: query
        name: execution_date
        schema:
          type: string
      - description: Filter greater than the value. Value must be formatted 'yyyy-mm-dd'.
        in: query
        name: execution_date.gt
        schema:
          type: string
      - description: Filter greater than or equal to the value. Value must be formatted 'yyyy-mm-dd'.
        in: query
        name: execution_date.gte
        schema:
          type: string
      - description: Filter less than the value. Value must be formatted 'yyyy-mm-dd'.
        in: query
        name: execution_date.lt
        schema:
          type: string
      - description: Filter less than or equal to the value. Value must be formatted 'yyyy-mm-dd'.
        in: query
        name: execution_date.lte
        schema:
          type: string
      - description: 'Classification of the share-change event. Possible values include: forward_split (share count increases), reverse_split (share count decreases), stock_dividend (shares issued as a dividend)'
        in: query
        name: adjustment_type
        schema:
          enum:
          - forward_split
          - reverse_split
          - stock_dividend
          type: string
      - description: Filter equal to any of the values. Multiple values can be specified by using a comma separated list.
        in: query
        name: adjustment_type.any_of
        schema:
          enum:
          - forward_split
          - reverse_split
          - stock_dividend
          type: string
      - description: Limit the maximum number of results returned. Defaults to '100' if not specified. The maximum allowed limit is '5000'.
        in: query
        name: limit
        schema:
          default: 100
          maximum: 5000
          minimum: 1
          type: integer
      - description: A comma separated list of sort columns. For each column, append '.asc' or '.desc' to specify the sort direction. The sort column defaults to 'execution_date' if not specified. The sort order defaults to 'desc' if not specified.
        in: query
        name: sort
        schema:
          default: execution_date.desc
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                request_id: 1
                results:
                - adjustment_type: forward_split
                  execution_date: '2005-02-28'
                  historical_adjustment_factor: 0.017857
                  id: E90a77bdf742661741ed7c8fc086415f0457c2816c45899d73aaa88bdc8ff6025
                  split_from: 1
                  split_to: 2
                  ticker: AAPL
                status: OK
              schema:
                properties:
                  next_url:
                    description: If present, this value can be used to fetch the next page.
                    type: string
                  request_id:
                    description: A request id assigned by the server.
                    type: string
                  results:
                    description: The results for this request.
                    items:
                      properties:
                        adjustment_type:
                          description: 'Classification of the share-change event. Possible values include: forward_split (share count increases), reverse_split (share count decreases), stock_dividend (shares issued as a dividend)'
                          type: string
                        execution_date:
                          description: Date when the stock split takes effect. The adjustment is applied overnight. On the prior trading day, the post-market session is the last session that shows pre-split prices. On the execution date, all trading is already adjusted for the split. This includes the pre-market session.
                          format: date
                          type: string
                        historical_adjustment_factor:
                          description: 'Cumulative adjustment factor used to offset split effects on historical prices. To adjust a historical price for splits: for a price on date D, find the first split whose `execution_date` is after date D and multiply the unadjusted price by the `historical_adjustment_factor`.'
                          format: double
                          type: number
                        id:
                          description: Unique identifier for each stock split event
                          type: string
                        split_from:
                          description: Denominator of the split ratio (old shares)
                          format: double
                          type: number
                        split_to:
                          description: Numerator of the split ratio (new shares)
                          format: double
                          type: number
                        ticker:
                          description: Stock symbol for the company that executed the split
                          type: string
                      required:
                      - adjustment_type
                      type: object
                    type: array
                  status:
                    description: The status of this request's response.
                    enum:
                    - OK
                    type: string
                required:
                - status
                - request_id
                - results
                type: object
          description: A list of results.
        '400':
          content:
            application/json:
              schema:
                properties:
                  error:
                    description: A message describing the source of the error.
                    type: string
                  request_id:
                    description: A request id assigned by the server.
                    type: string
                  status:
                    description: The status of this request's response.
                    enum:
                    - ERROR
                    type: string
                required:
                - status
                - request_id
                - error
                type: object
          description: An error message.
      tags:
      - us_stocks_reference
  /v1/reference/ipos:
    get:
      description: Contains comprehensive data about Initial Public Offerings (IPOs) and direct listings for US stocks, tracking both historical and pending offerings with detailed pricing, share, and timing information.
      operationId: get_v1_reference_ipos
      parameters:
      - description: The ticker symbol of the IPO event.
        in: query
        name: ticker
        schema:
          type: string
      - description: Filter equal to any of the values. Multiple values can be specified by using a comma separated list.
        in: query
        name: ticker.any_of
        schema:
          type: string
      - description: Filter greater than the value.
        in: query
        name: ticker.gt
        schema:
          type: string
      - description: Filter greater than or equal to the value.
        in: query
        name: ticker.gte
        schema:
          type: string
      - description: Filter less than the value.
        in: query
        name: ticker.lt
        schema:
          type: string
      - description: Filter less than or equal to the value.
        in: query
        name: ticker.lte
        schema:
          type: string
      - description: Nine-character alphanumeric code that uniquely identifies a financial security in North America.
        in: query
        name: us_code
        schema:
          type: string
      - description: Filter equal to any of the values. Multiple values can be specified by using a comma separated list.
        in: query
        name: us_code.any_of
        schema:
          type: string
      - description: Filter greater than the value.
        in: query
        name: us_code.gt
        schema:
          type: string
      - description: Filter greater than or equal to the value.
        in: query
        name: us_code.gte
        schema:
          type: string
      - description: Filter less than the value.
        in: query
        name: us_code.lt
        schema:
          type: string
      - description: Filter less than or equal to the value.
        in: query
        name: us_code.lte
        schema:
          type: string
      - description: International Securities Identification Number. This is a unique twelve-digit code that is assigned to every security issuance in the world.
        in: query
        name: isin
        schema:
          type: string
      - description: Filter equal to any of the values. Multiple values can be specified by using a comma separated list.
        in: query
        name: isin.any_of
        schema:
          type: string
      - description: Filter greater than the value.
        in: query
        name: isin.gt
        schema:
          type: string
      - description: Filter greater than or equal to the value.
        in: query
        name: isin.gte
        schema:
          type: string
      - description: Filter less than the value.
        in: query
        name: isin.lt
        schema:
          type: string
      - description: Filter less than or equal to the value.
        in: query
        name: isin.lte
        schema:
          type: string
      - description: First trading date for the newly listed entity. Value must be an integer timestamp in nanoseconds, formatted 'yyyy-mm-dd', or ISO 8601/RFC 3339 (e.g. '2024-05-28T20:27:41Z').
        in: query
        name: listing_date
        schema:
          type: string
      - description: Filter greater than the value. Value must be an integer timestamp in nanoseconds, formatted 'yyyy-mm-dd', or ISO 8601/RFC 3339 (e.g. '2024-05-28T20:27:41Z').
        in: query
        name: listing_date.gt
        schema:
          type: string
      - description: Filter greater than or equal to the value. Value must be an integer timestamp in nanoseconds, formatted 'yyyy-mm-dd', or ISO 8601/RFC 3339 (e.g. '2024-05-28T20:27:41Z').
        in: query
        name: listing_date.gte
        schema:
          type: string
      - description: Filter less than the value. Value must be an integer timestamp in nanoseconds, formatted 'yyyy-mm-dd', or ISO 8601/RFC 3339 (e.g. '2024-05-28T20:27:41Z').
        in: query
        name: listing_date.lt
        schema:
          type: string
      - description: Filter less than or equal to the value. Value must be an integer timestamp in nanoseconds, formatted 'yyyy-mm-dd', or ISO 8601/RFC 3339 (e.g. '2024-05-28T20:27:41Z').
        in: query
        name: listing_date.lte
        schema:
          type: string
      - description: The status of the IPO.
        in: query
        name: ipo_status
        schema:
          enum:
          - direct_listing_process
          - history
          - new
          - pending
          - postponed
          - rumor
          - withdrawn
          type: string
      - description: Filter equal to any of the values. Multiple values can be specified by using a comma separated list.
        in: query
        name: ipo_status.any_of
        schema:
          enum:
          - direct_listing_process
          - history
          - new
          - pending
          - postponed
          - rumor
          - withdrawn
          type: string
      - description: Limit the maximum number of results returned. Defaults to '10' if not specified. The maximum allowed limit is '1000'.
        in: query
        name: limit
        schema:
          default: 10
          maximum: 1000
          minimum: 1
          type: integer
      - description: A comma separated list of sort columns. For each column, append '.asc' or '.desc' to specify the sort direction. The sort column defaults to 'listing_date' if not specified. The sort order defaults to 'desc' if not specified.
        in: query
        name: sort
        schema:
          default: listing_date.desc
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                request_id: 6a7e466379af0a71039d60cc78e72282
                results:
                - announced_date: '2024-06-01'
                  currency_code: USD
                  final_issue_price: 17
                  highest_offer_price: 17
                  ipo_status: history
                  isin: US75383L1026
                  issuer_name: Rapport Therapeutics Inc.
                  last_updated: '2024-06-27'
                  listing_date: '2024-06-07'
                  lot_size: 100
                  lowest_offer_price: 17
                  max_shares_offered: 8000000
                  min_shares_offered: 1000000
                  primary_exchange: XNAS
                  security_description: Ordinary Shares
                  security_type: CS
                  shares_outstanding: 35376457
                  ticker: RAPP
                  total_offer_size: 136000000
                  us_code: 75383L102
                status: OK
              schema:
                properties:
                  next_url:
                    description: If present, this value can be used to fetch the next page.
                    type: string
                  request_id:
                    description: A request id assigned by the server.
                    type: string
                  results:
                    description: The results for this request.
                    items:
                      properties:
                        announced_date:
                          description: The date when the IPO event was announced.
                          format: int64
                          type: integer
                        currency_code:
                          description: Underlying currency of the security.
                          type: string
                        final_issue_price:
                          description: The price set by the company and its underwriters before the IPO goes live.
                          format: double
                          type: number
                        highest_offer_price:
                          description: The highest price within the IPO price range that the company might use to price the shares.
                          format: double
                          type: number
                        ipo_status:
                          description: The status of the IPO.
                          type: string
                        isin:
                          description: International Securities Identification Number. This is a unique twelve-digit code that is assigned to every security issuance in the world.
                          type: string
                        issuer_name:
                          description: Name of issuer.
                          type: string
                        last_updated:
                          description: The date when the IPO event was last modified.
                          format: int64
                          type: integer
                        listing_date:
                          description: First trading date for the newly listed entity.
                          format: int64
                          type: integer
                        lot_size:
                          description: The minimum number of shares that an investor may apply for during an IPO.
                          format: int64
                          type: integer
                        lowest_offer_price:
                          description: The lowest price within the IPO price range that the company is willing to offer its shares to investors.
                          format: double
                          type: number
                        max_shares_offered:
                          description: The upper limit of the shares that the company is offering to investors.
                          format: int64
                          type: integer
                        min_shares_offered:
                          description: The lower limit of shares that the company is willing to sell in the IPO.
                          format: int64
                          type: integer
                        primary_exchange:
                          description: Market Identifier Code (MIC) of the primary exchange where the security is listed. The Market Identifier Code (MIC) (ISO 10383) is a unique identification code used to identify securities trading exchanges, regulated and non-regulated trading markets.
                          type: string
                        security_description:
                          description: A brief description of the security. e.g. Class A Shares
                          type: string
                        security_type:
                          description: The classification of the stock. For example, CS stands for Common Stock.
                          type: string
                        shares_outstanding:
                          description: The total number of shares that the company has issued and are held by investors.
                          format: int64
                          type: integer
                        ticker:
                          description: The ticker symbol of the IPO event.
                          type: string
                        total_offer_size:
                          description: The total amount raised by the company for IPO.
                          format: double
                          type: number
                        us_code:
                          description: Nine-character alphanumeric code that uniquely identifies a financial security in North America.
                          type: string
                      type: object
                    type: array
                  status:
                    description: The status of this request's response.
                    enum:
                    - OK
                    type: string
                required:
                - status
                - request_id
                - results
                type: object
          description: A list of results.
        '400':
          content:
            application/json:
              schema:
                properties:
                  error:
                    description: A message describing the source of the error.
                    type: string
                  request_id:
                    description: A request id assigned by the server.
                    type: string
                  status:
                    description: The status of this request's response.
                    enum:
                    - ERROR
                    type: string
                required:
                - status
                - request_id
                - error
                type: object
          description: An error message.
      tags:
      - us_stocks_reference
components:
  securitySchemes:
    apiKey:
      in: query
      name: apiKey
      type: apiKey
x-polygon-order:
  crypto:
    market:
    - launchpad: shared
      paths:
      - /v2/aggs/ticker/{cryptoTicker}/range/{multiplier}/{timespan}/{from}/{to}
    - launchpad: exclusive
      paths:
      - /v1/summaries
    - paths:
      - /v2/aggs/grouped/locale/global/market/crypto/{date}
    - paths:
      - /v1/open-close/crypto/{from}/{to}/{date}
    - paths:
      - /v2/aggs/ticker/{cryptoTicker}/prev
    - paths:
      - /v3/trades/{cryptoTicker}
    - paths:
      - /v1/historic/crypto/{from}/{to}/{date}
    - paths:
      - /v1/last/crypto/{from}/{to}
    - group: Snapshots
      paths:
      - /v2/snapshot/locale/global/markets/crypto/tickers
      - /v2/snapshot/locale/global/markets/crypto/{direction}
      - /v2/snapshot/locale/global/markets/crypto

# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/polygon/refs/heads/main/openapi/polygon-us-stocks-reference-api-openapi.yml