---
title: "List instruments"
method: POST
path: "/v1/refdata/instruments"
tags: ["ReferenceData"]
---

# List instruments

`POST /v1/refdata/instruments`

Returns a list of instruments matching the request

## Request body

- ListInstrumentsRequest — Request for listing instruments with optional filters and pagination.
  - `pageSize` integer — Results per page (default: 50, max: 1000)
  - `pageToken` string — Pagination cursor from previous response
  - `symbols` string[] — Filter by specific instrument symbols
  - `productId` string — Filter by product ID
  - `tradableFilter` 'TRADABLE_FILTER_TRADABLE' | 'TRADABLE_FILTER_NON_TRADABLE' | 'TRADABLE_FILTER_ALL' — TradableFilter for filtering instruments by tradability. TRADABLE returns instruments where nonTradable=false. NON_TRADABLE returns instruments where nonTradable=true. ALL returns all instruments regardless of tradability.
  - `states` InstrumentState[] — Filter by instrument states (e.g., INSTRUMENT_STATE_OPEN)
  - `eventSeries` string — Filter by event series (e.g., 'nfl', 'nba', 'cbb')
  - `eventCategory` string — Filter by event category (e.g., 'SPR', 'POL', 'CRY')
  - `clearingSym` string — Filter by clearing symbol prefix (e.g., 'AEC-NFL')
  - `startTimeGte` string — Filter instruments starting on or after this date (format: 'YYYY-MM-DD')
  - `startTimeLte` string — Filter instruments starting on or before this date
  - `endTimeGte` string — Filter instruments expiring on or after this date
  - `endTimeLte` string — Filter instruments expiring on or before this date
  - `filter` InstrumentFilter — InstrumentFilter for advanced instrument queries. Both whereClause and fieldFilters can be used independently or combined (ANDed together).
    - `whereClause` string — SQL-like string expression. Supported operators: =, LIKE (with % wildcard), AND. Supported columns: state, symbol, event_series, event_category, clearing_sym, clearing_house, product_id. Do NOT use instrument_product, outcome_type, or event_subcategory (causes HTTP 500).
    - `fieldFilters` FieldFilter[] — Structured type-safe filters. ANDed with whereClause if both provided.
      - `field` string — Column name to filter on. Supported: state, symbol, event_series, event_category, clearing_sym, clearing_house, product_id.
      - `operator` 'FILTER_OPERATOR_UNSPECIFIED' | 'FILTER_OPERATOR_EQ' | 'FILTER_OPERATOR_LIKE' | 'FILTER_OPERATOR_IN' — FilterOperator defines comparison operators for FieldFilter. **EQ**: Exact match (=) **LIKE**: SQL LIKE pattern (% wildcard) **IN**: Match any value in list
      - `stringValue` string — String value to compare against (for EQ, LIKE)
      - `stringList` StringList — StringList for IN operator.
        - `values` string[] — List of string values

## Response `200`

A successful response.

- ListInstrumentsResponse — Response with list of instruments and pagination info.
  - `instruments` Instrument[] — List of matching instruments
    - `symbol` string
    - `tickSize` number, double
    - `baseCurrency` string
    - `multiplier` number, double
    - `minimumTradeQty` string, int64
    - `startDate` Date — Date represents a calendar date.
      - `year` integer
      - `month` integer
      - `day` integer
    - `expirationDate` Date — Date represents a calendar date.
      - `year` integer
      - `month` integer
      - `day` integer
    - `terminationDate` Date — Date represents a calendar date.
      - `year` integer
      - `month` integer
      - `day` integer
    - `tradingSchedule` TradingHours[]
      - `daysOfWeek` integer[]
      - `timeOfDay` TimeOfDay — TimeOfDay represents a time of day.
        - `hours` integer
        - `minutes` integer
        - `seconds` integer
      - `duration` string
      - `state` 'INSTRUMENT_STATE_CLOSED' | 'INSTRUMENT_STATE_OPEN' | 'INSTRUMENT_STATE_PREOPEN' | 'INSTRUMENT_STATE_SUSPENDED' | 'INSTRUMENT_STATE_EXPIRED' | 'INSTRUMENT_STATE_TERMINATED' | 'INSTRUMENT_STATE_HALTED' | 'INSTRUMENT_STATE_MATCH_AND_CLOSE_AUCTION' | 'INSTRUMENT_STATE_PENDING' — **PENDING**: Initial state for a newly created instrument which has not yet begun trading. **CLOSED**: No order entry, modification, cancellation, or matching. Day orders expired. **OPEN**: Continuous order entry and matching. **PREOPEN**: Orders accepted, no matching. Dutch Auction on transition to OPEN. **MATCH_AND_CLOSE_AUCTION**: Like PREOPEN, matches on transition out. **SUSPENDED**: Cancel only. No entry, modification, or matching. **HALTED**: Like SUSPENDED, no cancels allowed. **EXPIRED**: All resting orders expired, no new orders. **TERMINATED**: Order book removed, all orders and positions closed.
      - `hideMarketData` boolean
      - `expireAllOrders` boolean
    - `description` string
    - `clearingHouse` string
    - `minimumUnaffiliatedFirms` string, int64
    - `nonTradable` boolean
    - `jsonAttributes` string
    - `productId` string
    - `priceLimit` PriceLimit — PriceLimit describes optional price limits on an instrument.
      - `low` string, int64
      - `high` string, int64
      - `lowSet` boolean
      - `highSet` boolean
      - `relativeLow` number, double
      - `relativeHigh` number, double
      - `relativeLowSet` boolean
      - `relativeHighSet` boolean
    - `orderSizeLimit` OrderSizeLimit — OrderSizeLimit describes optional order size limits on an instrument.
      - `low` string, int64
      - `high` string, int64
      - `lowSet` boolean
      - `highSet` boolean
      - `totalNotionalLow` string, int64
      - `totalNotionalHigh` string, int64
      - `totalNotionalLowSet` boolean
      - `totalNotionalHighSet` boolean
    - `expirationTime` TimeOfDay — TimeOfDay represents a time of day.
      - `hours` integer
      - `minutes` integer
      - `seconds` integer
    - `tradeSettlementPeriod` string, int64
    - `state` 'INSTRUMENT_STATE_CLOSED' | 'INSTRUMENT_STATE_OPEN' | 'INSTRUMENT_STATE_PREOPEN' | 'INSTRUMENT_STATE_SUSPENDED' | 'INSTRUMENT_STATE_EXPIRED' | 'INSTRUMENT_STATE_TERMINATED' | 'INSTRUMENT_STATE_HALTED' | 'INSTRUMENT_STATE_MATCH_AND_CLOSE_AUCTION' | 'INSTRUMENT_STATE_PENDING' — **PENDING**: Initial state for a newly created instrument which has not yet begun trading. **CLOSED**: No order entry, modification, cancellation, or matching. Day orders expired. **OPEN**: Continuous order entry and matching. **PREOPEN**: Orders accepted, no matching. Dutch Auction on transition to OPEN. **MATCH_AND_CLOSE_AUCTION**: Like PREOPEN, matches on transition out. **SUSPENDED**: Cancel only. No entry, modification, or matching. **HALTED**: Like SUSPENDED, no cancels allowed. **EXPIRED**: All resting orders expired, no new orders. **TERMINATED**: Order book removed, all orders and positions closed.
    - `priceScale` string, int64
    - `fractionalQtyScale` string, int64
    - `settlementCurrency` string
    - `settlementPriceScale` string, int64
    - `metadata` object — Additional instrument metadata including sports league, market category, and game identifiers
    - `eventAttributes` EventAttributes — EventAttributes contains event-specific resolution and settlement details.
      - `question` string — Event resolution question
      - `payoutValue` string, int64 — Payout value on resolution
      - `eventDisplayName` string — Display name for the event
      - `eventId` string — Event identifier
      - `strikeValue` string — Strike value
      - `evaluationType` string — Evaluation comparison operator
      - `strikeUnit` string — Unit of the strike value
      - `calculationMethod` string — Calculation method for resolution
      - `timeSpecifier` string — Time specifier for the event
      - `positionAccountabilityValue` string, int64 — Position accountability limit value
    - `createTime` string, date-time — Instrument creation timestamp (RFC 3339)
    - `updateTime` string, date-time — Last update timestamp (RFC 3339)
  - `nextPageToken` string — Token for fetching next page (empty if no more results)
  - `eof` boolean — True when no more results available

---

[API](https://skmtc.net/polymarket/apis/portfolio-api.md) · [All operations](https://skmtc.net/polymarket/apis/portfolio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/polymarket/portfolio-api/revisions/150874842db1/schema)