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

# Get a list of instruments.

> Returns a paginated list of instruments.



## OpenAPI

````yaml api-reference/openapi.json get /v1/instruments
openapi: 3.0.0
info:
  title: CapyFin API
  description: >-
    The CapyFin API provides access to earnings reports with financials, key
    takeaways, revenue breakdowns, and forward guidance, delivered through a
    powerful, developer-friendly API. For support or enterprise access, please
    contact us at support@capyfin.com.
  version: 1.0.0
  contact:
    name: CapyFin Support
    url: https://capyfin.com/support
    email: support@capyfin.com
servers:
  - url: https://api.capyfin.com
    description: CapyFin API
security:
  - ApiKeyQuery: []
  - ApiKeyHeader: []
tags: []
paths:
  /v1/instruments:
    get:
      tags:
        - Instruments API
      summary: Get a list of instruments.
      description: Returns a paginated list of instruments.
      operationId: getInstruments
      parameters:
        - name: name
          required: false
          in: query
          schema:
            type: string
        - name: symbol
          required: false
          in: query
          description: Filter by symbol. Accepts multiple symbols separated by commas.
          schema:
            type: string
        - name: type
          required: true
          in: query
          schema:
            type: string
        - name: sector
          required: true
          in: query
          schema:
            type: string
        - name: industry
          required: true
          in: query
          schema:
            type: string
        - name: index
          required: false
          in: query
          description: Filter by index. Accepts multiple indices separated by commas.
          schema:
            enum:
              - SPX500
              - DJ30
              - NSDQ100
            type: string
        - name: country
          required: false
          in: query
          description: >-
            Filter by country (ISO 3166-1 alpha-2 country code). Accepts
            multiple countries separated by commas.
          schema:
            example: US,GB
            type: string
        - name: orderBy
          required: false
          in: query
          description: >-
            Sorts results by a field or aggregate expressions. Format for field
            sort: 'fieldName:order' (e.g., 'returnYearToDate:asc', default is
            'desc'). For aggregates like sum or avg, use
            'operation(field1,field2):order' (e.g.,
            'sum(yearlyReturns.2023,yearlyReturns.2022)' or
            'avg(operatingMargin,grossIncomeMargin):asc')').
          schema:
            type: string
        - name: fields
          required: false
          in: query
          description: Comma-separated list of fields to include in the response.
          schema:
            type: string
        - name: page
          required: false
          in: query
          description: 'Page number for pagination (default: 1).'
          schema:
            example: 1
            type: number
        - name: 5YearAverageNetProfitMargin
          required: false
          in: query
          description: 'Filter by average net profit margin. Comparators: gt, lt, gte, lte.'
          schema:
            example: gt:20
            type: string
        - name: 5YearAverageReturnOnInvestedCapital
          required: false
          in: query
          description: >-
            Filter by the average return on investment. Comparators: gt, lt,
            gte, lte.
          schema:
            example: gt:15
            type: string
        - name: grossIncomeMargin
          required: false
          in: query
          description: 'Filter by gross income margin. Comparators: gt, lt, gte, lte.'
          schema:
            example: gte:40
            type: string
        - name: operatingMargin
          required: false
          in: query
          description: 'Filter by operating margin. Comparators: gt, lt, gte, lte.'
          schema:
            example: gte:15
            type: string
        - name: quickRatio
          required: false
          in: query
          description: 'Filter by quick ratio. Comparators: gt, lt, gte, lte.'
          schema:
            example: gte:1.5
            type: string
        - name: totalDebtToEquityRatio
          required: false
          in: query
          description: 'Filter by total debt to equity ratio. Comparators: gt, lt, gte, lte.'
          schema:
            example: lt:0.5
            type: string
        - name: beta
          required: false
          in: query
          description: 'Filter by beta. Comparators: gt, lt, gte, lte.'
          schema:
            example: gt:1
            type: string
        - name: currentRatio
          required: false
          in: query
          description: 'Filter by current ratio. Comparators: gt, lt, gte, lte.'
          schema:
            example: gte:1
            type: string
        - name: peRatio
          required: false
          in: query
          description: 'Filter by P/E ratio. Comparators: gt, lt, gte, lte.'
          schema:
            example: lte:25
            type: string
        - name: dividendYield
          required: false
          in: query
          description: 'Filter by dividend yield percentage. Comparators: gt, lt, gte, lte.'
          schema:
            example: gt:5
            type: string
        - name: salesOrRevenue
          required: false
          in: query
          description: >-
            Filter by sales or revenue in dollars. Comparators: gt, lt, gte,
            lte.
          schema:
            example: gt:1000000
            type: string
        - name: eps
          required: false
          in: query
          description: 'Filter by earnings per share. Comparators: gt, lt, gte, lte.'
          schema:
            example: gt:1
            type: string
        - name: marketCapitalization
          required: false
          in: query
          description: 'Filter by market cap in dollars. Comparators: gt, lt, gte, lte.'
          schema:
            example: gte:100000000
            type: string
        - name: numberOfEmployees
          required: false
          in: query
          description: 'Filter by number of employees. Comparators: gt, lt, gte, lte.'
          schema:
            example: gte:1000
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedDto'
                  - properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/InstrumentListItemDto'
components:
  schemas:
    PaginatedDto:
      type: object
      properties:
        total:
          type: number
          description: The total number of results
          example: 100
        sub:
          type: boolean
          description: Whether this response includes subscriber-only data
          example: true
      required:
        - total
    InstrumentListItemDto:
      type: object
      properties:
        slug:
          type: string
          description: URL-friendly identifier for the instrument.
          example: nasdaq-aapl
        symbol:
          type: string
          description: The ticker symbol of the instrument.
          example: AAPL
        name:
          type: string
          description: The short name of the instrument.
          example: Apple
        type:
          type: string
          description: The type of the instrument.
          example: stock
          enum:
            - currency
            - commodity
            - index
            - stock
            - etf
            - crypto
        image:
          type: string
          description: URL to the instrument logo/image.
          example: https://example.com/aapl.png
        exchange:
          type: string
          description: The exchange on which the instrument is traded.
          example: nasdaq
        listed:
          type: boolean
          description: Whether the instrument is currently listed on an exchange.
          example: true
        closingPrice:
          type: number
          description: The last closing price of the instrument.
          example: 237.33
        returnLastDay:
          type: number
          description: >-
            The return of the instrument over the last day, expressed as a
            percentage.
          example: 1.92
        returnThisWeek:
          type: number
          description: >-
            The return of the instrument over the last week, expressed as a
            percentage.
          example: 3.24
        returnThisMonth:
          type: number
          description: >-
            The return of the instrument over the current month to date,
            expressed as a percentage.
          example: 5.06
        returnYearToDate:
          type: number
          description: >-
            The return of the instrument from the beginning of the year to the
            current date, expressed as a percentage.
          example: 23.26
        returnLastYear:
          type: number
          description: >-
            The return of the instrument over the last full calendar year,
            expressed as a percentage.
          example: 24.91
      required:
        - slug
        - symbol
        - name
        - type
        - exchange
        - listed
  securitySchemes:
    ApiKeyQuery:
      type: apiKey
      in: query
      name: apikey
      description: >-
        Pass your API key as a query parameter (e.g.,
        /endpoint?apikey=YOUR_API_KEY)
    ApiKeyHeader:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Pass your API key as a Bearer token in the header (e.g., Authorization:
        Bearer YOUR_API_KEY)

````