> **For AI agents:** this page is a focused, LLM-optimized view of a
> single Fiber AI operation. Before calling it, fetch the routing
> instructions at [`https://api.fiber.ai/llms.txt`](https://api.fiber.ai/llms.txt) and the full operation
> index at [`https://api.fiber.ai/ai-docs/index.md`](https://api.fiber.ai/ai-docs/index.md).

# financialInstrumentLookup

`POST /v1/finance/instrument`

**Tags:** `Market intelligence`

Look up a financial instrument

**Endpoint:** `https://api.fiber.ai/v1/finance/instrument`

## Description

Returns live market data for a stock, index, currency pair, or fund, including the headline quote, price movement, company facts, financial statements, related news, and a price history series.

⚡ Rate limit: 120 requests per 1 minute

💰 Cost: 2 credits per financial instrument lookup ⓘ

## Request body (JSON Schema)

```json
{
  "type": "object",
  "properties": {
    "apiKey": {
      "type": "string",
      "description": "Your Fiber API key"
    },
    "instrument": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "index"
              ]
            },
            "index": {
              "type": "string",
              "enum": [
                "SP_500",
                "DOW_JONES",
                "NASDAQ_100",
                "NASDAQ_COMPOSITE",
                "RUSSELL_1000",
                "RUSSELL_2000",
                "RUSSELL_3000",
                "FTSE_100"
              ],
              "description": "Named market index preset."
            }
          },
          "required": [
            "type",
            "index"
          ]
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "mutualFund"
              ]
            },
            "ticker": {
              "type": "string",
              "minLength": 1,
              "description": "Mutual fund ticker (e.g. `VTSAX`, `FXAIX`). This is for index funds and other mutual funds — NOT ETFs. ETFs like `SPY` or `QQQM` should use `stockOrEtf` instead."
            }
          },
          "required": [
            "type",
            "ticker"
          ]
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "stockOrEtf"
              ]
            },
            "ticker": {
              "type": "string",
              "minLength": 1,
              "description": "Ticker symbol for a stock or ETF (e.g. `AAPL`, `QQQM`, `BARC`)."
            },
            "exchange": {
              "type": "string",
              "minLength": 1,
              "description": "Exchange code (e.g. `NASDAQ`, `NYSE`, `NYSEARCA`, `LON`, `TYO`)."
            }
          },
          "required": [
            "type",
            "ticker",
            "exchange"
          ]
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "currencyPair"
              ]
            },
            "base": {
              "type": "string",
              "minLength": 3,
              "description": "Base currency code. Fiat currencies are 3 letters (e.g. `USD`, `GBP`, `JPY`); crypto codes may be longer (e.g. `BTC`, `MATIC`, `USDC`)."
            },
            "quote": {
              "type": "string",
              "minLength": 3,
              "description": "Quote currency code, using the same format as `base`."
            }
          },
          "required": [
            "type",
            "base",
            "quote"
          ]
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "customSymbol"
              ]
            },
            "symbol": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64,
              "description": "Fully-qualified symbol using Google Finance's format. You are responsible for the correct syntax. Examples: `AAPL:NASDAQ` (stock), `SPY:NYSEARCA` (ETF), `VTSAX:MUTF` (mutual fund), `EUR-USD` (currency pair), `BTC-USD` (crypto), `NIFTY_50:INDEXNSE` (index)."
            }
          },
          "required": [
            "type",
            "symbol"
          ]
        }
      ],
      "description": "How to identify the instrument. Use `index` for a named market index, `mutualFund` for a mutual fund, `stockOrEtf` for a stock or ETF, `currencyPair` for a forex or crypto pair, or `customSymbol` for any other format."
    },
    "window": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "1D",
        "5D",
        "1M",
        "6M",
        "YTD",
        "1Y",
        "5Y",
        "MAX",
        null
      ],
      "description": "Time range for the price history graph. Omit for `1D` (default, recommended). Setting a non-default window may result in less information being available, so we suggest leaving this null unless you have a strong reason not to."
    }
  },
  "required": [
    "apiKey",
    "instrument"
  ]
}
```

## Response — success (JSON Schema)

```json
{
  "type": "object",
  "properties": {
    "output": {
      "type": "object",
      "properties": {
        "instrument": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "name": {
              "type": [
                "string",
                "null"
              ],
              "description": "Display name of the instrument (e.g. 'Alphabet Inc Class A')."
            },
            "ticker": {
              "type": [
                "string",
                "null"
              ],
              "description": "Ticker symbol without the exchange (e.g. 'GOOGL')."
            },
            "exchange": {
              "type": [
                "string",
                "null"
              ],
              "description": "Exchange code (e.g. 'NASDAQ')."
            },
            "currency": {
              "type": [
                "string",
                "null"
              ],
              "pattern": "^[A-Z]{3,6}$",
              "description": "Currency the quote is denominated in — fiat (e.g. 'USD', 'GBP') or crypto (e.g. 'BTC', 'USDC'). Minor-unit exchanges such as London in pence are converted to the major unit so every price matches this code."
            }
          },
          "description": "Core identity of the looked-up instrument."
        },
        "quote": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "price": {
              "type": [
                "number",
                "null"
              ],
              "description": "Latest traded price as a number."
            },
            "currency": {
              "type": [
                "string",
                "null"
              ],
              "pattern": "^[A-Z]{3,6}$",
              "description": "Currency the price is denominated in — fiat (e.g. 'USD', 'GBP') or crypto (e.g. 'BTC', 'USDC')."
            },
            "priceChange": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "percentage": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Percent change versus the prior session."
                },
                "amount": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Absolute price change versus the prior session."
                },
                "direction": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "enum": [
                    "up",
                    "down",
                    null
                  ],
                  "description": "Whether the price moved up or down."
                },
                "currency": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "pattern": "^[A-Z]{3,6}$",
                  "description": "Currency the price change amount and percentage are denominated in (e.g. 'USD', 'GBP')."
                }
              },
              "description": "Magnitude and direction of the most recent price change."
            },
            "quotedAt": {
              "type": [
                "string",
                "null"
              ],
              "description": "ISO 8601 timestamp of when the quote was observed."
            }
          },
          "description": "Latest regular-session quote."
        },
        "extendedHoursQuote": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "price": {
              "type": [
                "number",
                "null"
              ],
              "description": "Latest traded price as a number."
            },
            "currency": {
              "type": [
                "string",
                "null"
              ],
              "pattern": "^[A-Z]{3,6}$",
              "description": "Currency the price is denominated in — fiat (e.g. 'USD', 'GBP') or crypto (e.g. 'BTC', 'USDC')."
            },
            "priceChange": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "percentage": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Percent change versus the prior session."
                },
                "amount": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Absolute price change versus the prior session."
                },
                "direction": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "enum": [
                    "up",
                    "down",
                    null
                  ],
                  "description": "Whether the price moved up or down."
                },
                "currency": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "pattern": "^[A-Z]{3,6}$",
                  "description": "Currency the price change amount and percentage are denominated in (e.g. 'USD', 'GBP')."
                }
              },
              "description": "Magnitude and direction of the most recent price change."
            },
            "quotedAt": {
              "type": [
                "string",
                "null"
              ],
              "description": "ISO 8601 timestamp of when the quote was observed."
            }
          },
          "description": "Extended-hours (pre/post-market) quote when reported separately."
        },
        "keyStats": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "currency": {
              "type": [
                "string",
                "null"
              ],
              "pattern": "^[A-Z]{3,6}$",
              "description": "Currency the price-denominated statistics are reported in (e.g. 'USD', 'BTC')."
            },
            "open": {
              "type": [
                "number",
                "null"
              ],
              "description": "Opening price for the current session."
            },
            "high": {
              "type": [
                "number",
                "null"
              ],
              "description": "Session high."
            },
            "low": {
              "type": [
                "number",
                "null"
              ],
              "description": "Session low."
            },
            "marketCap": {
              "type": [
                "number",
                "null"
              ],
              "description": "Market capitalization in the instrument's currency. Values from minor-unit exchanges are converted to major units."
            },
            "averageVolume": {
              "type": [
                "number",
                "null"
              ],
              "description": "Average trading volume."
            },
            "volume": {
              "type": [
                "number",
                "null"
              ],
              "description": "Current session volume."
            },
            "dividendYieldPercentage": {
              "type": [
                "number",
                "null"
              ],
              "description": "Dividend yield as a percentage (e.g. 0.26 for 0.26%)."
            },
            "peRatio": {
              "type": [
                "number",
                "null"
              ],
              "description": "Price-to-earnings ratio."
            },
            "fiftyTwoWeekHigh": {
              "type": [
                "number",
                "null"
              ],
              "description": "52-week high price."
            },
            "fiftyTwoWeekLow": {
              "type": [
                "number",
                "null"
              ],
              "description": "52-week low price."
            },
            "earningsPerShare": {
              "type": [
                "number",
                "null"
              ],
              "description": "Trailing earnings per share (EPS), denominated in the instrument's currency. EPS is the portion of a company's profit allocated to each outstanding share — higher values generally indicate stronger profitability."
            },
            "beta": {
              "type": [
                "number",
                "null"
              ],
              "description": "Beta relative to the market: a measure of how volatile the instrument is compared to the overall market. Beta > 1 means it tends to amplify market moves; beta < 1 means it tends to be more stable."
            },
            "sharesOutstanding": {
              "type": [
                "number",
                "null"
              ],
              "description": "Number of shares outstanding."
            }
          },
          "description": "Typed key statistics when available."
        },
        "companyInfo": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "description": {
              "type": [
                "string",
                "null"
              ],
              "description": "Short company or fund description."
            },
            "descriptionUrl": {
              "type": [
                "string",
                "null"
              ],
              "description": "URL for the full company description."
            },
            "ceoName": {
              "type": [
                "string",
                "null"
              ],
              "description": "Chief executive officer name."
            },
            "employeeCount": {
              "type": [
                "integer",
                "null"
              ],
              "description": "Number of employees."
            },
            "foundedDate": {
              "type": [
                "string",
                "null"
              ],
              "description": "ISO 8601 founding date: full 'YYYY-MM-DD' when the day is known, otherwise just 'YYYY'."
            },
            "headquarters": {
              "type": [
                "string",
                "null"
              ],
              "description": "Headquarters location."
            },
            "sector": {
              "type": [
                "string",
                "null"
              ],
              "description": "Sector or industry classification."
            },
            "websiteUrl": {
              "type": [
                "string",
                "null"
              ],
              "description": "Company website URL."
            }
          },
          "description": "Company information when available — description, leadership, sector, headquarters, etc."
        },
        "financials": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "object",
            "properties": {
              "statement": {
                "type": "string",
                "enum": [
                  "incomeStatement",
                  "balanceSheet",
                  "cashFlow",
                  "other"
                ],
                "description": "Which financial statement this group represents."
              },
              "periods": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "object",
                  "properties": {
                    "periodEndDate": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Calendar date the reporting period ended, as YYYY-MM-DD. Null when only a year or a quarter number is available, since the period's end depends on the company's fiscal calendar."
                    },
                    "periodLabel": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Period label such as 'Jun 2026', 'Q2 2026', or '2025'. Use periodEndDate to order or compare periods; a label may follow either the calendar year or the company's own fiscal year."
                    },
                    "periodType": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "enum": [
                        "quarterly",
                        "annual",
                        null
                      ],
                      "description": "Whether the period is quarterly or annual."
                    },
                    "currency": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "pattern": "^[A-Z]{3,6}$",
                      "description": "Currency of the reported values."
                    },
                    "lineItems": {
                      "type": [
                        "array",
                        "null"
                      ],
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Line-item name (e.g. 'Revenue')."
                          },
                          "value": {
                            "type": [
                              "number",
                              "null"
                            ],
                            "description": "Reported value for the period."
                          },
                          "changePercentage": {
                            "type": [
                              "number",
                              "null"
                            ],
                            "description": "Percent change versus the comparable prior period."
                          }
                        },
                        "description": "A single line item in a financial statement."
                      },
                      "description": "Line items reported for this period."
                    }
                  },
                  "description": "One reporting period of statement data."
                },
                "description": "Reporting periods included in this statement."
              }
            },
            "required": [
              "statement"
            ],
            "description": "A grouped financial statement with its reporting periods."
          },
          "description": "Quarterly and annual financial statements when available."
        },
        "news": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "object",
            "properties": {
              "title": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Article headline."
              },
              "url": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "URL of the article."
              },
              "source": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Publisher name."
              },
              "publishedAt": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time",
                "description": "ISO 8601 publication timestamp (e.g. '2026-07-28T14:30:00Z')."
              },
              "isPublishedAtEstimated": {
                "type": [
                  "boolean",
                  "null"
                ],
                "description": "Whether the publishedAt value is an estimate (true) or the exact publication timestamp (false). An estimate means only an approximate time like a date or hour was available from the source."
              },
              "thumbnailUrl": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Thumbnail image URL."
              }
            },
            "description": "A news article related to the instrument."
          },
          "description": "Recent news articles related to the instrument."
        },
        "priceHistory": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "object",
            "properties": {
              "price": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Price at this point."
              },
              "currency": {
                "type": [
                  "string",
                  "null"
                ],
                "pattern": "^[A-Z]{3,6}$",
                "description": "Currency of the price."
              },
              "at": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ISO 8601 timestamp of the price point."
              },
              "volume": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Trading volume at this point, when available."
              }
            },
            "description": "A single point on the price history series."
          },
          "description": "Recent price history for the instrument."
        }
      }
    },
    "chargeInfo": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "method": {
              "type": "string",
              "enum": [
                "charged-now"
              ]
            },
            "creditsCharged": {
              "type": "number"
            },
            "lowCreditAlert": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "getMoreCreditsUrl": {
                  "type": "string",
                  "format": "uri",
                  "description": "URL to top up credits or restart billing cycle to get fresh credits."
                },
                "message": {
                  "type": "string",
                  "description": "Human-readable credits warning."
                },
                "availableCredits": {
                  "type": "number",
                  "description": "Number of credits remaining in the current billing period."
                }
              },
              "required": [
                "getMoreCreditsUrl",
                "message",
                "availableCredits"
              ],
              "description": "Contains a link to get more credits, a warning message, and the remaining credit count."
            }
          },
          "required": [
            "method",
            "creditsCharged"
          ],
          "description": "Credits were charged immediately for this operation"
        },
        {
          "type": "object",
          "properties": {
            "method": {
              "type": "string",
              "enum": [
                "charging-later"
              ]
            },
            "message": {
              "type": "string"
            },
            "lowCreditAlert": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "getMoreCreditsUrl": {
                  "type": "string",
                  "format": "uri",
                  "description": "URL to top up credits or restart billing cycle to get fresh credits."
                },
                "message": {
                  "type": "string",
                  "description": "Human-readable credits warning."
                },
                "availableCredits": {
                  "type": "number",
                  "description": "Number of credits remaining in the current billing period."
                }
              },
              "required": [
                "getMoreCreditsUrl",
                "message",
                "availableCredits"
              ],
              "description": "Contains a link to get more credits, a warning message, and the remaining credit count."
            }
          },
          "required": [
            "method",
            "message"
          ],
          "description": "Credits will be charged after the operation completes"
        },
        {
          "type": "object",
          "properties": {
            "method": {
              "type": "string",
              "enum": [
                "charged-for-async-process"
              ]
            },
            "creditsCharged": {
              "type": "number"
            },
            "message": {
              "type": "string"
            },
            "lowCreditAlert": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "getMoreCreditsUrl": {
                  "type": "string",
                  "format": "uri",
                  "description": "URL to top up credits or restart billing cycle to get fresh credits."
                },
                "message": {
                  "type": "string",
                  "description": "Human-readable credits warning."
                },
                "availableCredits": {
                  "type": "number",
                  "description": "Number of credits remaining in the current billing period."
                }
              },
              "required": [
                "getMoreCreditsUrl",
                "message",
                "availableCredits"
              ],
              "description": "Contains a link to get more credits, a warning message, and the remaining credit count."
            }
          },
          "required": [
            "method",
            "creditsCharged",
            "message"
          ],
          "description": "Credits that were charged for an asynchronous operation"
        },
        {
          "type": "object",
          "properties": {
            "method": {
              "type": "string",
              "enum": [
                "free"
              ]
            },
            "message": {
              "type": "string"
            },
            "lowCreditAlert": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "getMoreCreditsUrl": {
                  "type": "string",
                  "format": "uri",
                  "description": "URL to top up credits or restart billing cycle to get fresh credits."
                },
                "message": {
                  "type": "string",
                  "description": "Human-readable credits warning."
                },
                "availableCredits": {
                  "type": "number",
                  "description": "Number of credits remaining in the current billing period."
                }
              },
              "required": [
                "getMoreCreditsUrl",
                "message",
                "availableCredits"
              ],
              "description": "Contains a link to get more credits, a warning message, and the remaining credit count."
            }
          },
          "required": [
            "method",
            "message"
          ],
          "description": "No credits were charged for this operation"
        },
        {
          "type": "object",
          "properties": {
            "method": {
              "type": "string",
              "enum": [
                "credits-refunded"
              ]
            },
            "creditsRefunded": {
              "type": "number"
            },
            "message": {
              "type": "string"
            },
            "lowCreditAlert": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "getMoreCreditsUrl": {
                  "type": "string",
                  "format": "uri",
                  "description": "URL to top up credits or restart billing cycle to get fresh credits."
                },
                "message": {
                  "type": "string",
                  "description": "Human-readable credits warning."
                },
                "availableCredits": {
                  "type": "number",
                  "description": "Number of credits remaining in the current billing period."
                }
              },
              "required": [
                "getMoreCreditsUrl",
                "message",
                "availableCredits"
              ],
              "description": "Contains a link to get more credits, a warning message, and the remaining credit count."
            }
          },
          "required": [
            "method",
            "creditsRefunded",
            "message"
          ],
          "description": "Credits were refunded for this operation"
        }
      ]
    },
    "warnings": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "description": "Full path to extraneous field (e.g., 'searchParams.ExtraField')"
          },
          "message": {
            "type": "string",
            "description": "Warning message"
          }
        },
        "required": [
          "field",
          "message"
        ]
      },
      "description": "Warnings about extraneous fields in request"
    },
    "advice": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string"
      },
      "description": "Tips, recommendations, and suggestions for using this API effectively."
    }
  },
  "required": [
    "output",
    "chargeInfo"
  ],
  "additionalProperties": false
}
```

---

Canonical JSON: [`https://api.fiber.ai/openapi.json`](https://api.fiber.ai/openapi.json)
Operation index: [`https://api.fiber.ai/ai-docs/index.md`](https://api.fiber.ai/ai-docs/index.md)