---
title: "Look up a financial instrument"
method: POST
path: "/v1/finance/instrument"
tags: ["Market intelligence"]
---

# Look up a financial instrument

`POST /v1/finance/instrument`

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.

<span>⚡ <strong>Rate limit:</strong> 120 requests per 1 minute</span>

<span>💰 <strong>Cost:</strong> 2 credits per financial instrument lookup&nbsp;<span title="Pricing shown is default pricing. Actual pricing may vary.">ⓘ</span></span>

## Request body

- object
  - `apiKey` string, required — Your Fiber API key
  - `instrument` union, required — 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.
    - object
      - `type` 'index', required
      - `index` 'SP_500' | 'DOW_JONES' | 'NASDAQ_100' | 'NASDAQ_COMPOSITE' | 'RUSSELL_1000' | 'RUSSELL_2000' | 'RUSSELL_3000' | 'FTSE_100', required — Named market index preset.
    - object
      - `type` 'mutualFund', required
      - `ticker` string, required — 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.
    - object
      - `type` 'stockOrEtf', required
      - `ticker` string, required — Ticker symbol for a stock or ETF (e.g. `AAPL`, `QQQM`, `BARC`).
      - `exchange` string, required — Exchange code (e.g. `NASDAQ`, `NYSE`, `NYSEARCA`, `LON`, `TYO`).
    - object
      - `type` 'currencyPair', required
      - `base` string, required — Base currency code. Fiat currencies are 3 letters (e.g. `USD`, `GBP`, `JPY`); crypto codes may be longer (e.g. `BTC`, `MATIC`, `USDC`).
      - `quote` string, required — Quote currency code, using the same format as `base`.
    - object
      - `type` 'customSymbol', required
      - `symbol` string, required — 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).
  - `window` '1D' | '5D' | '1M' | '6M' | 'YTD' | '1Y' | '5Y' | 'MAX' | 'null', nullable — 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.

## Response `200`

Default Response

- object
  - `output` object, required
    - `instrument` object, nullable — Core identity of the looked-up instrument.
      - `name` string, nullable — Display name of the instrument (e.g. 'Alphabet Inc Class A').
      - `ticker` string, nullable — Ticker symbol without the exchange (e.g. 'GOOGL').
      - `exchange` string, nullable — Exchange code (e.g. 'NASDAQ').
      - `currency` string, nullable — 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.
    - `quote` object, nullable — Latest regular-session quote.
      - `price` number, nullable — Latest traded price as a number.
      - `currency` string, nullable — Currency the price is denominated in — fiat (e.g. 'USD', 'GBP') or crypto (e.g. 'BTC', 'USDC').
      - `priceChange` object, nullable — Magnitude and direction of the most recent price change.
        - `percentage` number, nullable — Percent change versus the prior session.
        - `amount` number, nullable — Absolute price change versus the prior session.
        - `direction` 'up' | 'down' | 'null', nullable — Whether the price moved up or down.
        - `currency` string, nullable — Currency the price change amount and percentage are denominated in (e.g. 'USD', 'GBP').
      - `quotedAt` string, nullable — ISO 8601 timestamp of when the quote was observed.
    - `extendedHoursQuote` object, nullable — Extended-hours (pre/post-market) quote when reported separately.
      - `price` number, nullable — Latest traded price as a number.
      - `currency` string, nullable — Currency the price is denominated in — fiat (e.g. 'USD', 'GBP') or crypto (e.g. 'BTC', 'USDC').
      - `priceChange` object, nullable — Magnitude and direction of the most recent price change.
        - `percentage` number, nullable — Percent change versus the prior session.
        - `amount` number, nullable — Absolute price change versus the prior session.
        - `direction` 'up' | 'down' | 'null', nullable — Whether the price moved up or down.
        - `currency` string, nullable — Currency the price change amount and percentage are denominated in (e.g. 'USD', 'GBP').
      - `quotedAt` string, nullable — ISO 8601 timestamp of when the quote was observed.
    - `keyStats` object, nullable — Typed key statistics when available.
      - `currency` string, nullable — Currency the price-denominated statistics are reported in (e.g. 'USD', 'BTC').
      - `open` number, nullable — Opening price for the current session.
      - `high` number, nullable — Session high.
      - `low` number, nullable — Session low.
      - `marketCap` number, nullable — Market capitalization in the instrument's currency. Values from minor-unit exchanges are converted to major units.
      - `averageVolume` number, nullable — Average trading volume.
      - `volume` number, nullable — Current session volume.
      - `dividendYieldPercentage` number, nullable — Dividend yield as a percentage (e.g. 0.26 for 0.26%).
      - `peRatio` number, nullable — Price-to-earnings ratio.
      - `fiftyTwoWeekHigh` number, nullable — 52-week high price.
      - `fiftyTwoWeekLow` number, nullable — 52-week low price.
      - `earningsPerShare` number, nullable — 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` number, nullable — 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` number, nullable — Number of shares outstanding.
    - `companyInfo` object, nullable — Company information when available — description, leadership, sector, headquarters, etc.
      - `description` string, nullable — Short company or fund description.
      - `descriptionUrl` string, nullable — URL for the full company description.
      - `ceoName` string, nullable — Chief executive officer name.
      - `employeeCount` integer, nullable — Number of employees.
      - `foundedDate` string, nullable — ISO 8601 founding date: full 'YYYY-MM-DD' when the day is known, otherwise just 'YYYY'.
      - `headquarters` string, nullable — Headquarters location.
      - `sector` string, nullable — Sector or industry classification.
      - `websiteUrl` string, nullable — Company website URL.
    - `financials` object[], nullable — Quarterly and annual financial statements when available.
      - `statement` 'incomeStatement' | 'balanceSheet' | 'cashFlow' | 'other', required — Which financial statement this group represents.
      - `periods` object[], nullable — Reporting periods included in this statement.
        - `periodEndDate` string, nullable — 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` string, nullable — 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` 'quarterly' | 'annual' | 'null', nullable — Whether the period is quarterly or annual.
        - `currency` string, nullable — Currency of the reported values.
        - `lineItems` object[], nullable — Line items reported for this period.
          - `name` string, nullable — Line-item name (e.g. 'Revenue').
          - `value` number, nullable — Reported value for the period.
          - `changePercentage` number, nullable — Percent change versus the comparable prior period.
    - `news` object[], nullable — Recent news articles related to the instrument.
      - `title` string, nullable — Article headline.
      - `url` string, nullable — URL of the article.
      - `source` string, nullable — Publisher name.
      - `publishedAt` string, date-time, nullable — ISO 8601 publication timestamp (e.g. '2026-07-28T14:30:00Z').
      - `isPublishedAtEstimated` boolean, nullable — 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` string, nullable — Thumbnail image URL.
    - `priceHistory` object[], nullable — Recent price history for the instrument.
      - `price` number, nullable — Price at this point.
      - `currency` string, nullable — Currency of the price.
      - `at` string, nullable — ISO 8601 timestamp of the price point.
      - `volume` integer, nullable — Trading volume at this point, when available.
  - `chargeInfo` union, required
    - object — Credits were charged immediately for this operation
      - `method` 'charged-now', required
      - `creditsCharged` number, required
      - `lowCreditAlert` object, nullable — Contains a link to get more credits, a warning message, and the remaining credit count.
        - `getMoreCreditsUrl` string, uri, required — URL to top up credits or restart billing cycle to get fresh credits.
        - `message` string, required — Human-readable credits warning.
        - `availableCredits` number, required — Number of credits remaining in the current billing period.
    - object — Credits will be charged after the operation completes
      - `method` 'charging-later', required
      - `message` string, required
      - `lowCreditAlert` object, nullable — Contains a link to get more credits, a warning message, and the remaining credit count.
        - `getMoreCreditsUrl` string, uri, required — URL to top up credits or restart billing cycle to get fresh credits.
        - `message` string, required — Human-readable credits warning.
        - `availableCredits` number, required — Number of credits remaining in the current billing period.
    - object — Credits that were charged for an asynchronous operation
      - `method` 'charged-for-async-process', required
      - `creditsCharged` number, required
      - `message` string, required
      - `lowCreditAlert` object, nullable — Contains a link to get more credits, a warning message, and the remaining credit count.
        - `getMoreCreditsUrl` string, uri, required — URL to top up credits or restart billing cycle to get fresh credits.
        - `message` string, required — Human-readable credits warning.
        - `availableCredits` number, required — Number of credits remaining in the current billing period.
    - object — No credits were charged for this operation
      - `method` 'free', required
      - `message` string, required
      - `lowCreditAlert` object, nullable — Contains a link to get more credits, a warning message, and the remaining credit count.
        - `getMoreCreditsUrl` string, uri, required — URL to top up credits or restart billing cycle to get fresh credits.
        - `message` string, required — Human-readable credits warning.
        - `availableCredits` number, required — Number of credits remaining in the current billing period.
    - object — Credits were refunded for this operation
      - `method` 'credits-refunded', required
      - `creditsRefunded` number, required
      - `message` string, required
      - `lowCreditAlert` object, nullable — Contains a link to get more credits, a warning message, and the remaining credit count.
        - `getMoreCreditsUrl` string, uri, required — URL to top up credits or restart billing cycle to get fresh credits.
        - `message` string, required — Human-readable credits warning.
        - `availableCredits` number, required — Number of credits remaining in the current billing period.
  - `warnings` object[], nullable — Warnings about extraneous fields in request
    - `field` string, required — Full path to extraneous field (e.g., 'searchParams.ExtraField')
    - `message` string, required — Warning message
  - `advice` string[], nullable — Tips, recommendations, and suggestions for using this API effectively.

## Other responses

- `400` — Default Response
- `401` — Default Response
- `402` — Default Response
- `403` — Default Response
- `404` — Default Response
- `422` — Default Response
- `429` — Default Response
- `500` — Default Response
- `503` — Default Response

---

[API](https://skmtc.net/fiber/apis/fiber-ai-api.md) · [All operations](https://skmtc.net/fiber/apis/fiber-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fiber/fiber-ai-api/revisions/87ad9a3ecc4c/schema)