Browse all documentation

Short interest API reference

FINRA short interest of a US stock, latest and by settlement date

Overview

Short interest is the number of a stock's shares that investors have sold short and not yet bought back. FINRA publishes it for every US exchange-listed and OTC stock twice a month, for the 15th and for the last day of the month, each moved back to a business day when it is not one. Narwhal reads each file and serves the rows of the US listings it holds, so you can ask for one stock by listing id, such as XNAS:AAPL or XNYS:GME.

Every answer names its source, FINRA Equity Short Interest. The figures are FINRA's, not ours, and they are the positions as of the settlement date, not today.

Two routes. The first is the latest settlement date. The second is the history, newest first, paged with next_cursor. Both are the same calls as the equities MCP tool's short_interest and short_interest_history actions.

Base URL: https://api.narwhalapi.com. The MCP tool is equities, with one action for each route below.

What every account gets

WhatEvery account
Latest short interestIncluded
Short interest historyEvery settlement date we hold, from one year back

See pricing for what a call costs. A request is charged at the price of its API unless a route says otherwise.

  • A settlement date reaches us about two weeks after it. FINRA published the 30 October 2026 positions on 16 November 2026, so the latest answer is always two to three weeks old.
  • The settlement date is the 15th or the last day of the month, moved back to the previous New York Stock Exchange business day. Each file replaces nothing: a new date adds a row.
  • FINRA can revise a published file. revised is true when FINRA marked the row revised or when we saw its figures change after we first read them. The figures you get are the newest.
  • days_to_cover is short shares divided by average daily volume. FINRA writes 999.99 when the volume is 0. That is a placeholder, not a number, so we send null.
  • change_percent is left out when the previous figure is 0. Short interest as a percent of the shares floating is not given: we hold no float figure.
  • A row is served for a listing only when the company agrees, not just the ticker. After taking out case, punctuation and filler words (Inc, Corp, Holdings, Trust, Class A, Common Stock, ADR), FINRA's issue name and our listing's name must share more than half of the words of the shorter one and the same series numeral (II, III, Four), and for an ETF it is enough that the fund sponsor's name is in FINRA's, which cuts names at 30 characters. A ticker we cannot tie to the right company this way is stored and not served: it is 404 not_covered, which is also the answer when a company reused an old ticker or was renamed.
  • US listings only. A listing outside the US is 404 not_covered. So is a US listing FINRA has no row for, such as a warrant or a unit whose symbol does not match one of ours. An unknown id is 404 not_found. Neither is charged.
  • The terms of FINRA's data limit it to non-commercial use; Narwhal serves it with the owner's decision, names FINRA on every answer, and does not alter the figures.
  • The history pages 24 settlement dates by default, up to 500. start and end are inclusive settlement dates as YYYY-MM-DD. A page with rows and a next_cursor has more: send the cursor back with the same other parameters.

Endpoints

Every route is a GET and needs your key in the Authorization: Bearer header. The examples show the shape of an answer, not live data.

Latest short interest of one stock

GET /v1/equities/{id}/short-interest

FINRA's latest short interest of one US listing: shares sold short at the newest settlement date, the figure before it, the change in percent, FINRA's average daily volume and days to cover (null when the volume is 0, where FINRA writes a placeholder). Published twice a month, about two weeks after the settlement date. Every answer names FINRA as the source. A listing outside the US, or one FINRA has no row for, is 404 not_covered. One call.

MCP: tool equities, action short_interest.

Parameters

ParameterWhereRequiredTypeMeaning
idpathYesstringListing id: the exchange's four-letter code, a colon and the ticker, for example XNAS:MSFT or XNYS:BRK.B. A bare US ticker such as MSFT also works when it names one US listing; the answer carries the canonical id. Share classes use a dot (BRK.B); BRK-B is accepted.

Response fields

FieldTypeSentMeaning
idstringAlwaysCanonical listing id.
settlement_datedateAlwaysThe day the positions are as of: the 15th or the last day of a month, moved back to a business day.
short_sharesstringAlwaysShares sold short and not covered at the settlement date, whole shares.
previous_short_sharesstringAlwaysThe same figure at the previous settlement date.
change_percentstringOptionalshort_shares against previous_short_shares in percent (10.03 means 10.03%), 2 places. Left out when the previous figure is 0.
average_daily_volumestringOptionalFINRA's average daily share volume. Left out when FINRA gives none.
days_to_coverstringAlwaysshort_shares divided by average_daily_volume, 2 places. Null when the volume is 0: FINRA writes 999.99 there as a placeholder, and it is not sent.
revisedbooleanAlwaysTrue when FINRA marked the row revised or we saw its figures change.
sourcealways "FINRA Equity Short Interest"OptionalWhere the figures come from.
Request
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/equities/XNAS:AAPL/short-interest"
Example response
{
  "id": "XNAS:AAPL",
  "settlement_date": "2026-10-30",
  "short_shares": "144791472",
  "previous_short_shares": "131591865",
  "change_percent": "10.03",
  "average_daily_volume": "43085075",
  "days_to_cover": "3.36",
  "revised": false,
  "source": "FINRA Equity Short Interest"
}

Short interest history of one stock

GET /v1/equities/{id}/short-interest/history

FINRA's short interest of one US listing at each settlement date (the 15th and the last day of a month, moved back to a business day), newest first: shares sold short, the figure before it, the change in percent, FINRA's average daily volume and days to cover (null when the volume is 0). Every answer names FINRA as the source. Figures come out about two weeks after the settlement date. start and end limit the dates; up to 500 dates a page, with next_cursor. A listing outside the US, or one FINRA has no row for, is 404 not_covered. One call a page.

The cursor is the settlement date of the last row of the page. A cursor that is not a date is 400 invalid_cursor.

MCP: tool equities, action short_interest_history.

Parameters

ParameterWhereRequiredTypeMeaning
idpathYesstringListing id: the exchange's four-letter code, a colon and the ticker, for example XNAS:MSFT or XNYS:BRK.B. A bare US ticker such as MSFT also works when it names one US listing; the answer carries the canonical id. Share classes use a dot (BRK.B); BRK-B is accepted.
startqueryNostringFirst settlement date, YYYY-MM-DD (inclusive).
endqueryNostringLast settlement date, YYYY-MM-DD (inclusive).
limitqueryNointegerSettlement dates a page, newest first.
cursorqueryNostringThe next_cursor of the last page.

Response fields

FieldTypeSentMeaning
idstringAlwaysCanonical listing id.
short_interestlist of objectAlwaysNewest settlement date first.
short_interest[].settlement_datedateAlwaysThe day the positions are as of.
short_interest[].short_sharesstringAlwaysShares sold short, whole shares.
short_interest[].previous_short_sharesstringAlwaysThe figure at the previous settlement date.
short_interest[].change_percentstringOptionalChange in percent, 2 places. Left out when the previous figure is 0.
short_interest[].average_daily_volumestringOptionalFINRA's average daily share volume. Left out when FINRA gives none.
short_interest[].days_to_coverstringAlwaysDays to cover, 2 places; null when the volume is 0.
short_interest[].revisedbooleanAlwaysTrue when the row was revised.
next_cursorstringAlwaysPass as cursor for the next page; null on the last page.
sourcealways "FINRA Equity Short Interest"OptionalWhere the figures come from.
Request
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/equities/XNAS:AAPL/short-interest/history?limit=3"
Example response
{
  "id": "XNAS:AAPL",
  "short_interest": [
    {
      "settlement_date": "2026-10-30",
      "short_shares": "144791472",
      "previous_short_shares": "131591865",
      "change_percent": "10.03",
      "average_daily_volume": "43085075",
      "days_to_cover": "3.36",
      "revised": false
    },
    {
      "settlement_date": "2026-10-15",
      "short_shares": "131591865",
      "previous_short_shares": "120763539",
      "change_percent": "8.97",
      "average_daily_volume": "35498663",
      "days_to_cover": "3.71",
      "revised": false
    },
    {
      "settlement_date": "2026-09-30",
      "short_shares": "120763539",
      "previous_short_shares": "128753092",
      "change_percent": "-6.21",
      "average_daily_volume": "39858260",
      "days_to_cover": "3.03",
      "revised": false
    }
  ],
  "next_cursor": "2026-09-30",
  "source": "FINRA Equity Short Interest"
}

Errors

Errors use the shared problem shape with a request_id. See Errors and credits for the shape and the credit headers. Failed requests are not charged.

CodeStatusMeaning
invalid_query400A parameter is missing, unknown, repeated or outside its range.
invalid_id400An id or pair is not written the way this API expects.
not_found404No such listing, fund or pair.
not_covered404The market, country or company is not covered yet.
invalid_cursor400The cursor is not one this request returned, or it comes from a different request.
insufficient_credits402Your credit balance is less than the request costs.
area_unavailable503This area cannot answer right now.

Was this page helpful?