> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cdp.coinbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List instruments

> Returns a page of instruments. Requires MARKET_DATA permission.



## OpenAPI

````yaml /api-reference/derivatives-predictions-api/rest-api/cpm-spec.json get /api/v1/instruments
openapi: 3.0.3
info:
  title: CPM Public REST API
  version: 0.1.0
servers:
  - url: https://api.example.com
    variables: {}
security:
  - auth_api_key: []
  - auth_timestamp: []
  - auth_passphrase: []
  - auth_signature: []
paths:
  /api/v1/instruments:
    get:
      tags:
        - Reference
      summary: List instruments
      description: Returns a page of instruments. Requires MARKET_DATA permission.
      operationId: listInstrumentsV1
      parameters:
        - name: id
          in: query
          description: Filter by instrument ID. Repeatable.
          required: false
          deprecated: false
          allowEmptyValue: false
          schema:
            type: string
        - name: ticker
          in: query
          description: Case-insensitive substring of the ticker.
          required: false
          deprecated: false
          allowEmptyValue: false
          schema:
            type: string
        - name: title
          in: query
          description: Case-insensitive substring of the title.
          required: false
          deprecated: false
          allowEmptyValue: false
          schema:
            type: string
        - name: event_ticker
          in: query
          description: Case-insensitive substring of the event ticker.
          required: false
          deprecated: false
          allowEmptyValue: false
          schema:
            type: string
        - name: series_ticker
          in: query
          description: Case-insensitive substring of the series ticker.
          required: false
          deprecated: false
          allowEmptyValue: false
          schema:
            type: string
        - name: group_ticker
          in: query
          description: Case-insensitive substring of the group ticker.
          required: false
          deprecated: false
          allowEmptyValue: false
          schema:
            type: string
        - name: status
          in: query
          description: >-
            Filter by lifecycle status. Repeatable. DRAFT returns 400. Deleted
            instruments are listed with their last status.
          required: false
          deprecated: false
          allowEmptyValue: false
          schema:
            type: string
        - name: category
          in: query
          description: Filter by the linked Series category. Repeatable.
          required: false
          deprecated: false
          allowEmptyValue: false
          schema:
            type: string
        - name: updated_time_after
          in: query
          description: >-
            Only instruments whose updated_time is after this value, in Unix
            epoch milliseconds (exclusive).
          required: false
          deprecated: false
          allowEmptyValue: false
          schema:
            type: string
        - name: updated_time_before
          in: query
          description: >-
            Only instruments whose updated_time is before this value, in Unix
            epoch milliseconds (exclusive).
          required: false
          deprecated: false
          allowEmptyValue: false
          schema:
            type: string
        - name: list_time_after
          in: query
          description: >-
            Only instruments whose list_time is after this value, in Unix epoch
            milliseconds (exclusive).
          required: false
          deprecated: false
          allowEmptyValue: false
          schema:
            type: string
        - name: list_time_before
          in: query
          description: >-
            Only instruments whose list_time is before this value, in Unix epoch
            milliseconds (exclusive).
          required: false
          deprecated: false
          allowEmptyValue: false
          schema:
            type: string
        - name: open_time_after
          in: query
          description: >-
            Only instruments whose open_time is after this value, in Unix epoch
            milliseconds (exclusive).
          required: false
          deprecated: false
          allowEmptyValue: false
          schema:
            type: string
        - name: open_time_before
          in: query
          description: >-
            Only instruments whose open_time is before this value, in Unix epoch
            milliseconds (exclusive).
          required: false
          deprecated: false
          allowEmptyValue: false
          schema:
            type: string
        - name: close_time_after
          in: query
          description: >-
            Only instruments whose close_time is after this value, in Unix epoch
            milliseconds (exclusive).
          required: false
          deprecated: false
          allowEmptyValue: false
          schema:
            type: string
        - name: close_time_before
          in: query
          description: >-
            Only instruments whose close_time is before this value, in Unix
            epoch milliseconds (exclusive).
          required: false
          deprecated: false
          allowEmptyValue: false
          schema:
            type: string
        - name: settlement_time_after
          in: query
          description: >-
            Only instruments whose settlement_time is after this value, in Unix
            epoch milliseconds (exclusive).
          required: false
          deprecated: false
          allowEmptyValue: false
          schema:
            type: string
        - name: settlement_time_before
          in: query
          description: >-
            Only instruments whose settlement_time is before this value, in Unix
            epoch milliseconds (exclusive).
          required: false
          deprecated: false
          allowEmptyValue: false
          schema:
            type: string
        - name: sort
          in: query
          description: >-
            Sort field. Only updated_time is accepted. Without sort, results are
            ordered newest first by ID.
          required: false
          deprecated: false
          allowEmptyValue: false
          schema:
            type: string
        - name: order
          in: query
          description: >-
            Sort direction: asc or desc. Default desc. Used only with
            sort=updated_time.
          required: false
          deprecated: false
          allowEmptyValue: false
          schema:
            type: string
        - name: limit
          in: query
          description: Page size. Default 100, maximum 1000.
          required: false
          deprecated: false
          allowEmptyValue: false
          schema:
            type: string
        - name: cursor
          in: query
          description: >-
            Opaque cursor from the previous page's cursor field. Omit on the
            first request.
          required: false
          deprecated: false
          allowEmptyValue: false
          schema:
            type: string
      responses:
        '200':
          description: Instruments page
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/InstrumentReferenceResponse'
                  cursor:
                    type: string
        '400':
          description: Invalid parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferenceDataErrorResponse'
      deprecated: false
      security: []
components:
  schemas:
    InstrumentReferenceResponse:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          description: >-
            Instrument id, as a canonical decimal string. Use this id to place
            orders.
          example: '598471892347'
        ticker:
          type: string
          description: Unique instrument ticker. Treat it as an opaque identifier.
          example: NFL-GAMEWINNER-26NOV28LARSF-LAR
        series_ticker:
          type: string
          description: Ticker of the series this instrument belongs to.
          example: NFL-GAMEWINNER
        event_ticker:
          type: string
          description: Ticker of the event this instrument belongs to.
          example: 26NOV28LARSF
        group_ticker:
          type: string
          description: Ticker of the group of instruments that share this series and event.
          example: NFL-GAMEWINNER-26NOV28LARSF
        title:
          type: string
          description: Human-readable display name.
          example: Rams win
        proposition:
          type: string
          description: Plain-language criteria for the YES outcome.
          example: Los Angeles Rams win the game.
        disclaimers:
          type: string
          description: Compliance or eligibility disclaimer, or null when there is none.
          example: Professional football players may not trade this instrument.
        contract_size:
          type: string
          description: >-
            USDC notional per contract, as a decimal string. Its numeric value
            is 1.
          example: '1.00'
        price_level_structure:
          type: string
          description: >-
            Tick-size schedule for order prices: LINEAR_CENT, DECI_CENT, or
            TAPERED_DECI_CENT.
          example: LINEAR_CENT
        fractional_enabled:
          type: boolean
          description: Whether fractional contract quantities are enabled.
          example: true
        min_order_size:
          type: string
          description: Minimum order quantity in contracts, as a decimal string.
          example: '0.05'
        position_limit_per_instrument:
          type: string
          description: >-
            Maximum position in contracts that a firm may hold in this
            instrument, as a decimal string.
          example: '25000'
        speedbump_ms:
          type: string
          description: >-
            Speed-bump delay applied to aggressive orders, in milliseconds, as a
            decimal string. Null or 0 means no speed bump.
          example: '100'
        status:
          type: string
          description: >-
            Lifecycle status: LISTED, OPEN, PAUSE, CLOSED, DETERMINED, SETTLED,
            AMENDED, or DELISTED. Orders are accepted only while OPEN.
          example: OPEN
        list_time:
          type: integer
          format: int64
          description: >-
            Time of the first transition to LISTED, in Unix epoch milliseconds.
            Null until listed.
          example: 1795730000000
        open_time:
          type: integer
          format: int64
          description: >-
            Time of the first transition to OPEN, in Unix epoch milliseconds.
            Null until opened.
          example: 1795750000000
        close_time:
          type: integer
          format: int64
          description: >-
            Time of the most recent transition to CLOSED, in Unix epoch
            milliseconds. Null until closed.
        expected_open_time:
          type: integer
          format: int64
          description: >-
            Estimated open time for display, in Unix epoch milliseconds, or
            null. Non-binding: trading opens only when status becomes OPEN.
          example: 1795750000000
        expected_close_time:
          type: integer
          format: int64
          description: >-
            Estimated close time for display, in Unix epoch milliseconds, or
            null. Non-binding: trading closes only when status becomes CLOSED.
          example: 1795914000000
        settlement_outcome:
          type: string
          description: >-
            Determined outcome: YES, NO, or SCALAR. Null before the instrument
            is determined.
        settlement_value:
          type: string
          description: >-
            Payout per contract in USDC, from 0 through 1, as a decimal string.
            Null before the instrument is determined.
        settlement_time:
          type: integer
          format: int64
          description: >-
            Time of the transition to SETTLED, in Unix epoch milliseconds. Null
            until settled.
        open_interest:
          type: string
          description: >-
            Current open interest in contracts, as a decimal string. Null when
            the instrument has never traded.
          example: '1250.00'
        total_volume:
          type: string
          description: >-
            Total traded volume in contracts, as a decimal string. Null when the
            instrument has never traded.
          example: '8400.00'
        updated_time:
          type: integer
          format: int64
          description: >-
            Time of the instrument's latest change, in Unix epoch milliseconds.
            The updated_time filters compare this value.
          example: 1795750000123
        additional_metadata:
          $ref: '#/components/schemas/JsonElement'
          description: >-
            Market-specific instrument metadata as a JSON object. The fields
            vary by market.
      required:
        - fractional_enabled
        - updated_time
    ReferenceDataErrorResponse:
      type: object
      additionalProperties: false
      properties:
        error:
          $ref: '#/components/schemas/Error'
          description: Error details.
    JsonElement:
      type: object
      additionalProperties: false
      properties:
        jsonArray:
          type: boolean
        jsonObject:
          type: boolean
        jsonPrimitive:
          type: boolean
        jsonNull:
          type: boolean
        asJsonObject:
          $ref: '#/components/schemas/JsonObject'
        asJsonArray:
          $ref: '#/components/schemas/JsonArray'
        asJsonPrimitive:
          $ref: '#/components/schemas/JsonPrimitive'
        asJsonNull:
          $ref: '#/components/schemas/JsonNull'
        asBoolean:
          type: boolean
        asNumber:
          $ref: '#/components/schemas/Number'
        asString:
          type: string
        asDouble:
          type: number
          format: double
        asFloat:
          type: number
          format: float
        asLong:
          type: integer
          format: int64
        asInt:
          type: integer
          format: int32
        asByte:
          type: integer
          format: int32
        asCharacter:
          type: string
        asBigDecimal:
          type: string
        asBigInteger:
          $ref: '#/components/schemas/BigInteger'
        asShort:
          type: integer
          format: int32
      required:
        - jsonArray
        - jsonObject
        - jsonPrimitive
        - jsonNull
        - asBoolean
        - asDouble
        - asFloat
        - asLong
        - asInt
        - asByte
        - asCharacter
        - asShort
    Error:
      type: object
      additionalProperties: false
      properties:
        code:
          type: string
          description: >-
            Machine-readable error code, for example INVALID_PARAMETER,
            NOT_FOUND, or INTERNAL_ERROR.
          example: INVALID_PARAMETER
        message:
          type: string
          description: Human-readable description of the error.
          example: cursor is invalid or belongs to another resource type
        field:
          type: string
          description: >-
            Name of the request parameter that caused the error, or null when
            the error is not tied to one parameter.
          example: cursor
    JsonObject:
      type: object
      additionalProperties: false
      properties:
        jsonArray:
          type: boolean
        jsonObject:
          type: boolean
        jsonPrimitive:
          type: boolean
        jsonNull:
          type: boolean
        asJsonObject:
          $ref: '#/components/schemas/JsonObject'
        asJsonArray:
          $ref: '#/components/schemas/JsonArray'
        asJsonPrimitive:
          $ref: '#/components/schemas/JsonPrimitive'
        asJsonNull:
          $ref: '#/components/schemas/JsonNull'
        asBoolean:
          type: boolean
        asNumber:
          $ref: '#/components/schemas/Number'
        asString:
          type: string
        asDouble:
          type: number
          format: double
        asFloat:
          type: number
          format: float
        asLong:
          type: integer
          format: int64
        asInt:
          type: integer
          format: int32
        asByte:
          type: integer
          format: int32
        asCharacter:
          type: string
        asBigDecimal:
          type: string
        asBigInteger:
          $ref: '#/components/schemas/BigInteger'
        asShort:
          type: integer
          format: int32
        empty:
          type: boolean
        '':
          $ref: '#/components/schemas/JsonElement'
      required:
        - jsonArray
        - jsonObject
        - jsonPrimitive
        - jsonNull
        - asBoolean
        - asDouble
        - asFloat
        - asLong
        - asInt
        - asByte
        - asCharacter
        - asShort
        - empty
    JsonArray:
      type: object
      additionalProperties: false
      properties:
        jsonArray:
          type: boolean
        jsonObject:
          type: boolean
        jsonPrimitive:
          type: boolean
        jsonNull:
          type: boolean
        asJsonObject:
          $ref: '#/components/schemas/JsonObject'
        asJsonArray:
          $ref: '#/components/schemas/JsonArray'
        asJsonPrimitive:
          $ref: '#/components/schemas/JsonPrimitive'
        asJsonNull:
          $ref: '#/components/schemas/JsonNull'
        empty:
          type: boolean
        '':
          $ref: '#/components/schemas/JsonElement'
        asSingleElement:
          $ref: '#/components/schemas/JsonElement'
        asNumber:
          $ref: '#/components/schemas/Number'
        asString:
          type: string
        asDouble:
          type: number
          format: double
        asBigDecimal:
          type: string
        asBigInteger:
          $ref: '#/components/schemas/BigInteger'
        asFloat:
          type: number
          format: float
        asLong:
          type: integer
          format: int64
        asInt:
          type: integer
          format: int32
        asByte:
          type: integer
          format: int32
        asCharacter:
          type: string
        asShort:
          type: integer
          format: int32
        asBoolean:
          type: boolean
      required:
        - jsonArray
        - jsonObject
        - jsonPrimitive
        - jsonNull
        - empty
        - asDouble
        - asFloat
        - asLong
        - asInt
        - asByte
        - asCharacter
        - asShort
        - asBoolean
    JsonPrimitive:
      type: object
      additionalProperties: false
      properties:
        jsonArray:
          type: boolean
        jsonObject:
          type: boolean
        jsonPrimitive:
          type: boolean
        jsonNull:
          type: boolean
        asJsonObject:
          $ref: '#/components/schemas/JsonObject'
        asJsonArray:
          $ref: '#/components/schemas/JsonArray'
        asJsonPrimitive:
          $ref: '#/components/schemas/JsonPrimitive'
        asJsonNull:
          $ref: '#/components/schemas/JsonNull'
        boolean:
          type: boolean
        asBoolean:
          type: boolean
        number:
          type: boolean
        asNumber:
          $ref: '#/components/schemas/Number'
        string:
          type: boolean
        asString:
          type: string
        asDouble:
          type: number
          format: double
        asBigDecimal:
          type: string
        asBigInteger:
          $ref: '#/components/schemas/BigInteger'
        asFloat:
          type: number
          format: float
        asLong:
          type: integer
          format: int64
        asShort:
          type: integer
          format: int32
        asInt:
          type: integer
          format: int32
        asByte:
          type: integer
          format: int32
        asCharacter:
          type: string
      required:
        - jsonArray
        - jsonObject
        - jsonPrimitive
        - jsonNull
        - boolean
        - asBoolean
        - number
        - string
        - asDouble
        - asFloat
        - asLong
        - asShort
        - asInt
        - asByte
        - asCharacter
    JsonNull:
      type: object
      additionalProperties: false
      properties:
        jsonArray:
          type: boolean
        jsonObject:
          type: boolean
        jsonPrimitive:
          type: boolean
        jsonNull:
          type: boolean
        asJsonObject:
          $ref: '#/components/schemas/JsonObject'
        asJsonArray:
          $ref: '#/components/schemas/JsonArray'
        asJsonPrimitive:
          $ref: '#/components/schemas/JsonPrimitive'
        asJsonNull:
          $ref: '#/components/schemas/JsonNull'
        asBoolean:
          type: boolean
        asNumber:
          $ref: '#/components/schemas/Number'
        asString:
          type: string
        asDouble:
          type: number
          format: double
        asFloat:
          type: number
          format: float
        asLong:
          type: integer
          format: int64
        asInt:
          type: integer
          format: int32
        asByte:
          type: integer
          format: int32
        asCharacter:
          type: string
        asBigDecimal:
          type: string
        asBigInteger:
          $ref: '#/components/schemas/BigInteger'
        asShort:
          type: integer
          format: int32
      required:
        - jsonArray
        - jsonObject
        - jsonPrimitive
        - jsonNull
        - asBoolean
        - asDouble
        - asFloat
        - asLong
        - asInt
        - asByte
        - asCharacter
        - asShort
    Number:
      type: object
      additionalProperties: false
      properties: {}
    BigInteger:
      type: object
      additionalProperties: false
      properties:
        toomSlice:
          $ref: '#/components/schemas/BigInteger'
        lower:
          $ref: '#/components/schemas/BigInteger'
        upper:
          $ref: '#/components/schemas/BigInteger'
        lowestSetBit:
          type: integer
          format: int32
        probablePrime:
          type: boolean
        int:
          type: integer
          format: int32
      required:
        - lowestSetBit
        - probablePrime
        - int
  securitySchemes:
    auth_api_key:
      name: CB-ACCESS-KEY
      description: The API key string for the request
      in: header
      type: apiKey
    auth_timestamp:
      name: CB-ACCESS-TIMESTAMP
      description: The request timestamp (epoch seconds)
      in: header
      type: apiKey
    auth_passphrase:
      name: CB-ACCESS-PASSPHRASE
      description: The passphrase for the API key
      in: header
      type: apiKey
    auth_signature:
      name: CB-ACCESS-SIGN
      description: HMAC SHA-256 signature over TIMESTAMP + METHOD + REQUEST_PATH + BODY
      in: header
      type: apiKey

````