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:/. The MCP tool is equities, with one action for each route below.
What every account gets
| What | Every account |
|---|---|
| Latest short interest | Included |
| Short interest history | Every 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.
revisedis 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_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.to_ cover change_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.percent - 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_, which is also the answer when a company reused an old ticker or was renamed.covered - US listings only. A listing outside the US is 404
not_. 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 404covered not_. Neither is charged.found - 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.
startandendare inclusive settlement dates as YYYY-MM-DD. A page with rows and anext_has more: send the cursor back with the same other parameters.cursor
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_.
Parameters
| Parameter | Where | Required | Type | Meaning |
|---|---|---|---|---|
id | path | Yes | string | Listing 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
| Field | Type | Sent | Meaning |
|---|---|---|---|
id | string | Always | Canonical listing id. |
settlement_ | date | Always | The day the positions are as of: the 15th or the last day of a month, moved back to a business day. |
short_ | string | Always | Shares sold short and not covered at the settlement date, whole shares. |
previous_ | string | Always | The same figure at the previous settlement date. |
change_ | string | Optional | short_ against previous_ in percent (10.03 means 10.03%), 2 places. Left out when the previous figure is 0. |
average_ | string | Optional | FINRA's average daily share volume. Left out when FINRA gives none. |
days_ | string | Always | short_ divided by average_, 2 places. Null when the volume is 0: FINRA writes 999.99 there as a placeholder, and it is not sent. |
revised | boolean | Always | True when FINRA marked the row revised or we saw its figures change. |
source | always "FINRA Equity Short Interest" | Optional | Where the figures come from. |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/equities/XNAS:AAPL/short-interest"{
"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_. 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_.
Parameters
| Parameter | Where | Required | Type | Meaning |
|---|---|---|---|---|
id | path | Yes | string | Listing 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. |
start | query | No | string | First settlement date, YYYY-MM-DD (inclusive). |
end | query | No | string | Last settlement date, YYYY-MM-DD (inclusive). |
limit | query | No | integer | Settlement dates a page, newest first. |
cursor | query | No | string | The next_ of the last page. |
Response fields
| Field | Type | Sent | Meaning |
|---|---|---|---|
id | string | Always | Canonical listing id. |
short_ | list of object | Always | Newest settlement date first. |
short_ | date | Always | The day the positions are as of. |
short_ | string | Always | Shares sold short, whole shares. |
short_ | string | Always | The figure at the previous settlement date. |
short_ | string | Optional | Change in percent, 2 places. Left out when the previous figure is 0. |
short_ | string | Optional | FINRA's average daily share volume. Left out when FINRA gives none. |
short_ | string | Always | Days to cover, 2 places; null when the volume is 0. |
short_ | boolean | Always | True when the row was revised. |
next_ | string | Always | Pass as cursor for the next page; null on the last page. |
source | always "FINRA Equity Short Interest" | Optional | Where the figures come from. |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/equities/XNAS:AAPL/short-interest/history?limit=3"{
"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_. See Errors and credits for the shape and the credit headers. Failed requests are not charged.
| Code | Status | Meaning |
|---|---|---|
invalid_ | 400 | A parameter is missing, unknown, repeated or outside its range. |
invalid_ | 400 | An id or pair is not written the way this API expects. |
not_ | 404 | No such listing, fund or pair. |
not_ | 404 | The market, country or company is not covered yet. |
invalid_ | 400 | The cursor is not one this request returned, or it comes from a different request. |
insufficient_ | 402 | Your credit balance is less than the request costs. |
area_ | 503 | This area cannot answer right now. |
Was this page helpful?