Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Ninjas Short Interest API
description: 'Combined OpenAPI specification for every API Ninjas endpoint. Requests go to https://api.api-ninjas.com with an `X-Api-Key` header; get a free key at https://api-ninjas.com/register. Human-readable docs: https://api-ninjas.com/api. Index for LLMs: https://api-ninjas.com/llms.txt.'
version: 1.0.0
contact:
name: API Ninjas
url: https://api-ninjas.com
license:
name: Proprietary
servers:
- url: https://api.api-ninjas.com
description: API Ninjas Production
security:
- ApiKeyAuth: []
tags:
- name: Short Interest
description: 'Official US short interest as reported to FINRA under Rule 4560, covering 22,000+ exchange-listed and OTC equity securities with history back to December 2017. Enriched with data FINRA does not publish: short percent of shares outstanding and of public float (from SEC filings), dollar notional short, and a two-year percentile showing where the current reading sits in the stock''s own range. Companion endpoints cover daily short volume, SEC fails-to-deliver, and the settlement/publication calendar. Short interest is bi-weekly (24 times a year), published on the seventh business day after each settlement date.'
paths:
/v1/shortinterest:
get:
summary: Get short interest for a stock or ETF
operationId: getShortInterest
description: Returns the latest bi-weekly short interest for a security plus history, enriched with short percent of outstanding and float, dollar notional short, and a two-year percentile. The free tier returns the latest settlement date with the exact short percent of outstanding; premium plans unlock float-based metrics, the percentile, split-adjusted history and the full archive back to 2017.
parameters:
- name: ticker
in: query
required: true
description: The stock or ETF ticker symbol (e.g., GME). Share classes and preferred shares can be written in any common form, e.g. BRK.B, BRK-B, BRK/B or BRKB, and BAC.PRL or BAC-PL.
schema:
type: string
example: GME
- name: settlement_date
in: query
required: false
description: Return a specific settlement date in YYYY-MM-DD format. Short interest settles on the 15th and the last business day of each month.
schema:
type: string
format: date
example: '2026-07-31'
- name: limit
in: query
required: false
description: Number of historical settlement dates to return, 1 to 200. Defaults to 12. The free tier is limited to the latest date.
schema:
type: integer
minimum: 1
maximum: 200
example: 12
responses:
'200':
description: A JSON object with the security, the latest settlement-date reading, its SEC-derived enrichment (share count, float, notional, two-year percentile) and a history array. Premium fields are replaced with an upgrade message on the free tier.
content:
application/json:
schema:
type: object
properties:
ticker:
type: string
name:
type: string
exchange:
type: string
description: 'Listing venue: NYSE, NNM, SC, ARCA, BZX, AMEX, IEX or OTC.'
cik:
type: string
sector:
type: string
industry:
type: string
settlement_date:
type: string
format: date
description: 'The date the position was measured: the 15th or the last business day of a month.'
shares_short:
type: integer
description: Shares sold short and not yet covered.
previous_shares_short:
type: integer
description: The prior settlement date's short position.
change:
type: integer
description: Change in shares short since the prior settlement date.
change_percent:
type: number
description: Percent change in shares short since the prior settlement date.
average_daily_volume:
type: integer
description: Average daily trading volume used to compute days to cover.
days_to_cover:
type:
- number
- 'null'
description: Shares short divided by average daily volume, also called the short ratio. Null when average daily volume is zero and the ratio is undefined.
shares_outstanding:
type: integer
description: Total shares outstanding from the company's cover page, resolved to the value in effect at this settlement date.
shares_outstanding_as_of:
type: string
format: date
description: The cover-page date of the share count used.
short_percent_outstanding:
type: number
description: Shares short as a percent of shares outstanding. Exact.
float_shares:
type: integer
description: Estimated public float in shares. Premium.
short_percent_float:
type: number
description: Shares short as a percent of estimated public float. Premium.
float_estimated:
type: boolean
description: 'Always true: public float is disclosed as a dollar amount, so a share count is always derived. Premium.'
float_as_of:
type: string
format: date
description: The date the filer measured public float. Premium.
float_price_gap_days:
type: integer
description: Days between the float measurement date and the price used to convert dollars into shares. 0 is an exact-date conversion; larger values are less precise. Premium.
float_is_capped:
type: boolean
description: True when the derived float exceeded shares outstanding and was clamped to it. On these rows short_percent_float is a floor, not a measurement, and equals short_percent_outstanding. Premium.
close_price:
type: number
description: Price near the settlement date, for scaling a share count into dollars; not a quote. Premium.
price_date:
type: string
format: date
description: The date of the price used. Premium.
dollar_volume_short:
type: integer
description: Notional value of the short position in US dollars. Premium.
percentile_2y:
type: number
description: Where this reading sits in the stock's own trailing two-year range, 0-100. Answers whether a given percentage is high for this stock. Premium.
shares_short_split_adjusted:
type: integer
description: Shares short rescaled onto today's share basis so multi-year history stays comparable across splits. Premium.
is_revision:
type: boolean
description: True when this settlement date was restated after initial publication.
had_split:
type: boolean
description: True when a stock split affecting this record was flagged.
next_settlement_date:
type: string
format: date
next_publication_date:
type: string
format: date
description: When the next reading becomes available, so callers can schedule rather than poll.
source:
type: string
history:
type: array
items:
$ref: '#/components/schemas/ShortInterestRecord'
'400':
description: Bad request — missing or invalid parameters, or an invalid API key.
tags:
- Short Interest
/v1/shortinterestscreener:
get:
summary: Rank the whole market by short interest
operationId: getShortInterestScreener
description: Ranks every US security for a settlement date by short percent of float, short percent of outstanding, days to cover, two-week change, dollar notional short, or two-year percentile. This is how you find the most shorted stocks. Requires a Business plan or higher.
parameters:
- name: sort_by
in: query
required: false
description: Ranking metric.
schema:
type: string
enum:
- short_percent_float
- short_percent_outstanding
- days_to_cover
- change_percent
- dollar_volume_short
- percentile_2y
- shares_short
default: short_percent_float
- name: order
in: query
required: false
description: Sort direction.
schema:
type: string
enum:
- asc
- desc
default: desc
- name: settlement_date
in: query
required: false
description: Settlement date in YYYY-MM-DD format. Defaults to the most recent published date.
schema:
type: string
format: date
- name: exchange
in: query
required: false
description: Restrict to one listing venue.
schema:
type: string
enum:
- NYSE
- NNM
- SC
- ARCA
- BZX
- AMEX
- OTC
- IEX
- OTCBB
- name: sector
in: query
required: false
description: Restrict to one sector (e.g., Technology, Health Care).
schema:
type: string
example: Health Care
- name: min_short_percent_float
in: query
required: false
description: Minimum short percent of float.
schema:
type: number
example: 20
- name: min_days_to_cover
in: query
required: false
description: Minimum days to cover.
schema:
type: number
example: 5
- name: min_price
in: query
required: false
description: Minimum share price, useful for excluding sub-dollar names.
schema:
type: number
example: 5
- name: min_shares_outstanding
in: query
required: false
description: Minimum shares outstanding, a rough size filter.
schema:
type: number
example: 10000000
- name: exclude_capped_float
in: query
required: false
description: Set true to exclude rows where the derived float was clamped to shares outstanding, leaving only measured floats.
schema:
type: string
enum:
- 'true'
- 'false'
- name: max_float_price_gap_days
in: query
required: false
description: Only include rows whose float was converted using a price within this many days of the measurement date.
schema:
type: integer
example: 7
- name: limit
in: query
required: false
description: Number of results, 1 to 100. Defaults to 25.
schema:
type: integer
minimum: 1
maximum: 100
example: 25
responses:
'200':
description: A JSON object with the settlement date, the sort applied, a result count and a ranked results array. Each entry carries the same fields as /shortinterest.
content:
application/json:
schema:
type: object
properties:
settlement_date:
type: string
format: date
description: The settlement date ranked.
sort_by:
type: string
description: The metric used for ranking.
order:
type: string
description: Sort direction applied.
count:
type: integer
description: Number of results returned.
results:
type: array
description: Array of securities in ranked order.
items:
$ref: '#/components/schemas/ShortInterestScreenerResult'
'400':
description: Bad request, invalid parameters, or a plan below Business.
tags:
- Short Interest
/v1/shortvolume:
get:
summary: Get daily short sale volume
operationId: getShortVolume
description: 'Reg SHO daily short sale volume — the portion of a day''s OFF-EXCHANGE volume flagged as short sales. This is not short interest and not a percent of total market volume: FINRA covers only trades reported to its Trade Reporting Facilities, roughly 35-52% of consolidated volume. A ratio near 50% is normal and mostly reflects wholesalers filling retail buy orders from inventory. Updated every trading day, so it moves between bi-weekly short interest readings.'
parameters:
- name: ticker
in: query
required: true
description: The stock or ETF ticker symbol (e.g., GME). Share classes and preferred shares can be written in any common form, e.g. BRK.B, BRK-B, BRK/B or BRKB, and BAC.PRL or BAC-PL.
schema:
type: string
example: GME
- name: limit
in: query
required: false
description: Number of trading days to return, 1 to 250. Defaults to 30. The free tier is limited to the latest day.
schema:
type: integer
minimum: 1
maximum: 250
example: 30
responses:
'200':
description: A JSON object with the latest trading day (short volume, short-exempt volume, total off-exchange volume, ratio and reporting facilities), a 20-day average ratio, and a history array.
content:
application/json:
schema:
type: object
properties:
ticker:
type: string
description: The security's ticker symbol.
latest:
$ref: '#/components/schemas/ShortVolumeRecord'
average_short_volume_ratio_20d:
type: number
description: Mean short_volume_ratio over the last 20 trading days, a baseline to read today's figure against.
history:
type: array
description: Array of prior trading days with the same fields. Premium.
items:
$ref: '#/components/schemas/ShortVolumeRecord'
'400':
description: Bad request — missing or invalid parameters.
tags:
- Short Interest
/v1/failstodeliver:
get:
summary: Get SEC fails-to-deliver
operationId: getFailsToDeliver
description: Shares that did not settle on the contractual settlement date, published semi-monthly by the SEC.
parameters:
- name: ticker
in: query
required: true
description: The stock or ETF ticker symbol (e.g., GME). Share classes and preferred shares can be written in any common form, e.g. BRK.B, BRK-B, BRK/B or BRKB, and BAC.PRL or BAC-PL.
schema:
type: string
example: GME
- name: limit
in: query
required: false
description: Number of records to return, 1 to 250. Defaults to 30. The free tier is limited to the latest record.
schema:
type: integer
minimum: 1
maximum: 250
example: 30
responses:
'200':
description: A JSON object with the latest fails-to-deliver record, a trailing 12-month aggregate and a history array.
content:
application/json:
schema:
type: object
properties:
ticker:
type: string
description: The security's ticker symbol.
latest:
$ref: '#/components/schemas/FailsToDeliverRecord'
history:
type: array
description: Array of prior fail records with the same fields. Premium.
items:
$ref: '#/components/schemas/FailsToDeliverRecord'
trailing_12m:
type: object
description: Aggregate over the last year. Premium.
properties:
days_with_fails:
type: integer
description: Number of days with a fail record in the last year.
peak_quantity_failed:
type: integer
description: Largest quantity_failed in the last year.
average_quantity_failed:
type: integer
description: Average quantity_failed in the last year.
'400':
description: Bad request — missing or invalid parameters.
tags:
- Short Interest
/v1/shortinterestcalendar:
get:
summary: Get the short interest settlement and publication calendar
operationId: getShortInterestCalendar
description: Settlement dates, member reporting deadlines and publication dates. Short interest changes only 24 times a year, so this lets you schedule refreshes instead of polling. Available on every plan, including free.
parameters:
- name: year
in: query
required: false
description: Restrict to one calendar year (2018 onward).
schema:
type: integer
example: 2026
- name: upcoming
in: query
required: false
description: Set true to return only future, not-yet-published settlement dates in ascending order.
schema:
type: string
enum:
- 'true'
- 'false'
- name: limit
in: query
required: false
description: Number of dates to return, 1 to 120. Defaults to 24 (one year).
schema:
type: integer
minimum: 1
maximum: 120
example: 24
responses:
'200':
description: A JSON object with a count and a results array of settlement dates, member reporting deadlines and publication dates. Dates with is_published false carry a projected publication_date.
content:
application/json:
schema:
type: object
properties:
count:
type: integer
description: Number of dates returned.
results:
type: array
items:
$ref: '#/components/schemas/ShortInterestCalendarEntry'
'400':
description: Bad request — invalid parameters.
tags:
- Short Interest
components:
schemas:
ShortInterestCalendarEntry:
type: object
properties:
settlement_date:
type: string
format: date
description: The date on which short positions are measured.
reporting_due_date:
type: string
format: date
description: 'When members must have reported: the second business day after settlement, excluding market holidays.'
publication_date:
type: string
format: date
description: 'When the compiled figures are published: the seventh business day after settlement.'
is_published:
type: boolean
description: false for future dates, whose publication_date is therefore a projection.
securities_reported:
type:
- integer
- 'null'
description: Number of securities in the published file.
ShortInterestScreenerResult:
type: object
properties:
ticker:
type: string
description: The security's ticker symbol.
name:
type: string
description: Security name.
exchange:
type: string
description: 'Listing venue: NYSE, NNM, SC, ARCA, BZX, AMEX, IEX or OTC.'
sector:
type: string
description: Sector.
industry:
type: string
description: Industry.
shares_short:
type: integer
description: Shares sold short and not yet covered.
change_percent:
type: number
description: Percent change in shares short since the prior settlement date.
days_to_cover:
type:
- number
- 'null'
description: Shares short divided by average daily volume, also called the short ratio. Null when average daily volume is zero and the ratio is undefined.
shares_outstanding:
type: integer
description: Total shares outstanding, resolved to the value in effect at this settlement date.
short_percent_outstanding:
type: number
description: Shares short as a percent of shares outstanding. Exact.
float_shares:
type: integer
description: Estimated public float in shares.
short_percent_float:
type: number
description: Shares short as a percent of estimated public float.
float_estimated:
type: boolean
description: 'Always true: public float is disclosed as a dollar amount, so a share count is always derived.'
float_is_capped:
type: boolean
description: True when the derived float exceeded shares outstanding and was clamped to it. On these rows short_percent_float is a floor, not a measurement, and equals short_percent_outstanding.
close_price:
type: number
description: Price near the settlement date, for scaling a share count into dollars; not a quote.
dollar_volume_short:
type: integer
description: Notional value of the short position in US dollars.
percentile_2y:
type: number
description: Where this reading sits in the stock's own trailing two-year range, 0-100.
ShortVolumeRecord:
type: object
properties:
date:
type: string
format: date
description: The trading day.
short_volume:
type: integer
description: Shares sold short that day in off-exchange trading.
short_exempt_volume:
type: integer
description: Short sale volume exempt from the short sale price test.
total_volume:
type: integer
description: Total off-exchange volume reported that day. This is not consolidated market volume.
short_volume_ratio:
type: number
description: short_volume as a percent of total_volume. A share of off-exchange volume, not of total volume.
markets:
type: string
description: Reporting facilities that contributed, e.g. B,Q,N or O.
FailsToDeliverRecord:
type: object
properties:
settlement_date:
type: string
format: date
description: The settlement date of the fail record.
cusip:
type: string
description: CUSIP of the security.
name:
type: string
description: Security name.
quantity_failed:
type: integer
description: Shares that did not settle on the contractual settlement date.
price:
type: number
description: Closing price associated with the fail record.
dollar_value:
type: integer
description: quantity_failed multiplied by price, so fails are comparable across share prices.
ShortInterestRecord:
type: object
properties:
settlement_date:
type: string
format: date
description: The settlement date the position was measured on (the 15th or the last business day of a month).
shares_short:
type: integer
description: Shares sold short and not yet covered, as reported to FINRA.
previous_shares_short:
type: integer
description: The prior settlement date's short position.
change:
type: integer
description: Change in shares short since the prior settlement date.
change_percent:
type: number
description: Percent change in shares short since the prior settlement date.
average_daily_volume:
type: integer
description: Average daily trading volume used by FINRA to compute days to cover.
days_to_cover:
type:
- number
- 'null'
description: Shares short divided by average daily volume, also called the short ratio.
shares_outstanding:
type: integer
description: Total shares outstanding from the company's SEC cover page (dei:EntityCommonStockSharesOutstanding), resolved to the value in effect at this settlement date.
short_percent_outstanding:
type: number
description: Shares short as a percent of shares outstanding. Exact.
float_shares:
type: integer
description: Estimated public float in shares, derived from the SEC's dollar public-float disclosure. Premium.
short_percent_float:
type: number
description: Shares short as a percent of estimated public float. Estimated, not reported. Premium.
float_estimated:
type: boolean
description: Always true. Public float is disclosed by the SEC as a dollar amount, so a share count is always derived.
float_as_of:
type: string
format: date
description: The date the public float was measured by the filer. Premium.
float_price_gap_days:
type: integer
description: Days between the float measurement date and the price used to convert dollars to shares. 0 is an exact-date conversion; larger values are less precise. Premium.
float_is_capped:
type: boolean
description: True when the derived float exceeded shares outstanding and was clamped to it. On these rows short_percent_float is a floor, not a measurement. Premium.
shares_outstanding_as_of:
type: string
format: date
description: The cover-page date of the share count used.
close_price:
type: number
description: Price near the settlement date, from SEC fails-to-deliver filings. Premium.
price_date:
type: string
format: date
description: The date of the price used. Premium.
price_source:
type: string
description: Source of the price. Currently sec_ftd. Premium.
dollar_volume_short:
type: integer
description: Notional value of the short position in US dollars (shares short times price). Premium.
percentile_2y:
type: number
description: Where this reading sits in the stock's own trailing two-year range, 0-100. Answers whether a given percentage is high for this particular stock. Premium.
shares_short_split_adjusted:
type: integer
description: Shares short rescaled onto today's share basis so multi-year history remains comparable across stock splits. Premium.
is_revision:
type: boolean
description: True when FINRA restated this settlement date after initial publication.
had_split:
type: boolean
description: True when FINRA flagged a stock split affecting this record.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-Api-Key
externalDocs:
description: API Ninjas documentation
url: https://api-ninjas.com/api