# Short Interest & Fails-to-Deliver API — SEC FTD + FINRA (`malonestar/short-interest-ftd-monitor`) Actor Short interest & fails-to-deliver (FTD) API. Merges SEC FTD and FINRA short-interest disclosures into one per-ticker time series with change and spike flags. Keyless official sources. Market-structure DATA, not investment advice. - **URL**: https://apify.com/malonestar/short-interest-ftd-monitor.md - **Developed by:** [Kyle Maloney](https://apify.com/malonestar) (community) - **Categories:** Lead generation, Developer tools, Agents - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $6.00 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Short Interest & Fails-to-Deliver Monitor Merge two official US market-structure disclosures — **SEC Fails-to-Deliver (FTD)** and **FINRA consolidated short interest** — into one clean, per-ticker **time series** with **change and spike flags**. Keyless official sources, one normalized schema, ready to chart, alert on, or feed to an agent. > **This is market-structure DATA, not investment advice.** It reports publicly filed fails-to-deliver and short-interest figures and simple period-over-period math on them. It is not a signal, recommendation, or prediction to buy, sell, or hold any security. Do your own research. ### Who it's for - **Quant / data engineers** who want FTD and short interest already parsed, normalized, deduped, and joined per ticker instead of unzipping SEC pipe files and FINRA CSVs by hand. - **Market-structure & compliance researchers** tracking settlement fails and short-interest build-ups over time. - **Fintech / dashboard builders** who need a stable JSON feed of fails, deltas, and spike flags per symbol. - **AI agents** that need to answer "how have fails-to-deliver for X trended, and did they spike?" as a callable tool. ### What it does 1. Downloads the SEC semi-monthly FTD files (newest first, over your lookback), decompresses them, and parses the pipe-delimited layout into per-`(symbol, settlement_date)` records. 2. Optionally downloads FINRA consolidated short-interest files and joins them per ticker (as-of the nearest FINRA settlement date on or before each FTD period). 3. Builds a per-ticker **time series** and computes, for each period: `fails_delta`, `fails_pct_change`, a trailing average, and a `fails_spike` boolean (fails > `spikeMultiplier` x trailing average). When short interest is included it adds `short_interest`, `days_to_cover`, and their deltas. 4. Filters to your `tickers[]` (uppercased, client-side) and a `sinceDate` window. ### Example input ```json { "tickers": ["GME", "AMC"], "lookbackPeriods": 6, "spikeMultiplier": 3, "includeShortInterest": true, "shortInterestDates": ["2026-04-15", "2026-03-31"], "maxResults": 5000, "monitor": false } ```` Leave `tickers` empty to return every symbol in the files (capped by `maxResults`). Set `monitor: true` on a schedule to emit only newly published `(ticker, settlement_date)` rows. ### Output fields | Field | Description | |---|---| | `symbol` | Uppercased ticker | | `cusip` | CUSIP from the SEC FTD file | | `description` | Issuer / company name | | `settlement_date` | SEC settlement date (YYYY-MM-DD) | | `fails_quantity` | Total fails-to-deliver shares (SEC CNS aggregate) | | `price` | Prior-day close from the FTD file (null when SEC value is `.`) | | `fails_delta` / `fails_pct_change` | Change vs the ticker's prior period | | `fails_trailing_avg` | Average fails over the prior lookback periods | | `fails_spike` | True when fails > `spikeMultiplier` x trailing average | | `short_interest` / `short_interest_prev` | FINRA consolidated (OTC) short-interest shares | | `short_interest_delta` / `short_interest_pct_change` | Change vs the prior FINRA cycle | | `days_to_cover` | FINRA days-to-cover (short interest / avg daily volume) | | `short_pct_float` | Always null — float is not in the FINRA file (documented caveat) | | `short_interest_spike` | Short-interest spike flag | | `avg_daily_volume` | FINRA average daily volume | | `sources` | Which disclosures contributed (e.g. `["SEC FTD", "FINRA Short Interest"]`) | ### Use as an MCP tool This actor is callable by AI agents (Claude, Cursor, etc.) via [mcp.apify.com](https://mcp.apify.com). The field-level output descriptions make it a clean, chainable tool: an agent can pass `tickers` + a lookback and get back a structured fails/short-interest time series with spike flags to reason over — no scraping, no unzip, no CSV parsing. ### Sources & caveats - **SEC Fails-to-Deliver (FTD)** — semi-monthly ZIP files at `https://www.sec.gov/files/data/fails-deliver-data/cnsfails{YYYYMM}{a|b}.zip`, each containing a pipe-delimited `.txt` (`SETTLEMENT DATE | CUSIP | SYMBOL | QUANTITY (FAILS) | DESCRIPTION | PRICE`). The SEC requires a descriptive `User-Agent`; this actor sets one. Files are decompressed in-actor with the tiny pure-JS `fflate` library. The `a` file (first half of a month) publishes ~end of that month; the `b` file (second half) ~the 15th of the next month, so the newest period may not yet exist — the actor skips not-yet-published files gracefully. - **FINRA consolidated short interest** — bi-monthly keyless CSV at `https://cdn.finra.org/equity/otcmarket/biweekly/shrt{YYYYMMDD}.csv`. **Caveat:** this CDN file covers **OTC-market** equities; exchange-listed short interest is not in this particular file, so a ticker may have FTD data but no short-interest row. Float is not published, so `short_pct_float` is always null. Short interest is opt-in (`includeShortInterest`) and you supply the FINRA settlement dates. - Neither source guarantees accuracy or timeliness; both are official disclosures republished as-is with added transform. Values can be revised by the publisher. ### FAQ **Is this a short interest API?** Yes — it exposes SEC fails-to-deliver plus FINRA short interest as a normalized per-ticker JSON/CSV time series. **Where does fails-to-deliver data come from?** The SEC's official Fails-to-Deliver dataset (NSCC CNS aggregate), published semi-monthly. **How is a "spike" defined?** A period is flagged when its fails (or short interest) exceeds `spikeMultiplier` times the ticker's trailing average over the prior lookback periods. Default multiplier is 3. **Can I monitor for new data automatically?** Yes — run on an Apify schedule with `monitor: true` to emit only newly published `(ticker, settlement_date)` records. **Is this investment advice?** No. It is market-structure data and simple arithmetic on public filings. Nothing here is a recommendation. ### Pricing Pay-per-result: you pay per record returned (one merged `(ticker, settlement_date)` row = one result). Empty results cost only the tiny actor start. # Actor input Schema ## `tickers` (type: `array`): Stock ticker symbols to include (case-insensitive; matched client-side after uppercasing), e.g. \["GME", "AMC", "AAPL"]. Leave empty to return every symbol in the fetched files, capped by Max results. ## `sinceDate` (type: `string`): Only return records whose SEC settlement date is on or after this date. Applied after the time series is built, so the first returned period still shows its true change vs the prior period. Empty = no lower bound. ## `lookbackPeriods` (type: `integer`): How many SEC Fails-to-Deliver semi-monthly files to pull, newest first. SEC publishes two files per month (first half / second half), so 6 covers roughly the last three months. Larger windows give longer time series and steadier trailing averages. ## `spikeMultiplier` (type: `integer`): A record is flagged fails\_spike = true when its fails\_quantity exceeds this multiple of the ticker's trailing average fails (over the prior lookback periods). Default 3 (a 3x jump). Lower = more sensitive. ## `includeShortInterest` (type: `boolean`): Also fetch and merge FINRA consolidated (OTC-market) short-interest disclosures, adding short\_interest, days\_to\_cover, and their deltas. Requires Short interest dates below. NOTE: the FINRA CDN biweekly file covers OTC equities; exchange-listed short interest is not in this file, so some tickers may have FTD data but no short-interest row. ## `shortInterestDates` (type: `array`): FINRA bi-monthly settlement dates to fetch when Include FINRA short interest is on, e.g. \["2026-04-15", "2026-03-31"]. These are the dates FINRA publishes files for (mid-month and month-end). Each maps to https://cdn.finra.org/equity/otcmarket/biweekly/shrt{YYYYMMDD}.csv. ## `maxResults` (type: `integer`): Maximum number of merged per-ticker records to return after filtering. Each record is one (ticker, settlement date) row and is one billable result. ## `monitor` (type: `boolean`): When scheduled, emit only (ticker, settlement date) records not seen in previous runs — a recurring new-data alert. State is kept in the actor's key-value store. ## Actor input object example ```json { "tickers": [ "GME", "AMC" ], "lookbackPeriods": 6, "spikeMultiplier": 3, "includeShortInterest": false, "maxResults": 5000, "monitor": false } ``` # Actor output Schema ## `results` (type: `string`): Merged per-ticker FTD + short-interest records with change/spike flags, in the default dataset. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "tickers": [ "GME", "AMC" ] }; // Run the Actor and wait for it to finish const run = await client.actor("malonestar/short-interest-ftd-monitor").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "tickers": [ "GME", "AMC", ] } # Run the Actor and wait for it to finish run = client.actor("malonestar/short-interest-ftd-monitor").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "tickers": [ "GME", "AMC" ] }' | apify call malonestar/short-interest-ftd-monitor --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=malonestar/short-interest-ftd-monitor", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Short Interest & Fails-to-Deliver API — SEC FTD + FINRA", "description": "Short interest & fails-to-deliver (FTD) API. Merges SEC FTD and FINRA short-interest disclosures into one per-ticker time series with change and spike flags. Keyless official sources. Market-structure DATA, not investment advice.", "version": "1.0", "x-build-id": "Rurpbc7YLJ9vgfQ3e" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/malonestar~short-interest-ftd-monitor/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-malonestar-short-interest-ftd-monitor", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/malonestar~short-interest-ftd-monitor/runs": { "post": { "operationId": "runs-sync-malonestar-short-interest-ftd-monitor", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/malonestar~short-interest-ftd-monitor/run-sync": { "post": { "operationId": "run-sync-malonestar-short-interest-ftd-monitor", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "tickers": { "title": "Tickers", "type": "array", "description": "Stock ticker symbols to include (case-insensitive; matched client-side after uppercasing), e.g. [\"GME\", \"AMC\", \"AAPL\"]. Leave empty to return every symbol in the fetched files, capped by Max results.", "items": { "type": "string" } }, "sinceDate": { "title": "Since date (YYYY-MM-DD)", "type": "string", "description": "Only return records whose SEC settlement date is on or after this date. Applied after the time series is built, so the first returned period still shows its true change vs the prior period. Empty = no lower bound." }, "lookbackPeriods": { "title": "Lookback periods (SEC semi-monthly files)", "minimum": 1, "maximum": 48, "type": "integer", "description": "How many SEC Fails-to-Deliver semi-monthly files to pull, newest first. SEC publishes two files per month (first half / second half), so 6 covers roughly the last three months. Larger windows give longer time series and steadier trailing averages.", "default": 6 }, "spikeMultiplier": { "title": "Spike multiplier", "minimum": 1, "maximum": 100, "type": "integer", "description": "A record is flagged fails_spike = true when its fails_quantity exceeds this multiple of the ticker's trailing average fails (over the prior lookback periods). Default 3 (a 3x jump). Lower = more sensitive.", "default": 3 }, "includeShortInterest": { "title": "Include FINRA short interest", "type": "boolean", "description": "Also fetch and merge FINRA consolidated (OTC-market) short-interest disclosures, adding short_interest, days_to_cover, and their deltas. Requires Short interest dates below. NOTE: the FINRA CDN biweekly file covers OTC equities; exchange-listed short interest is not in this file, so some tickers may have FTD data but no short-interest row.", "default": false }, "shortInterestDates": { "title": "FINRA short-interest settlement dates (YYYY-MM-DD)", "type": "array", "description": "FINRA bi-monthly settlement dates to fetch when Include FINRA short interest is on, e.g. [\"2026-04-15\", \"2026-03-31\"]. These are the dates FINRA publishes files for (mid-month and month-end). Each maps to https://cdn.finra.org/equity/otcmarket/biweekly/shrt{YYYYMMDD}.csv.", "items": { "type": "string" } }, "maxResults": { "title": "Max results", "minimum": 1, "maximum": 200000, "type": "integer", "description": "Maximum number of merged per-ticker records to return after filtering. Each record is one (ticker, settlement date) row and is one billable result.", "default": 5000 }, "monitor": { "title": "Delta mode (only new settlement dates)", "type": "boolean", "description": "When scheduled, emit only (ticker, settlement date) records not seen in previous runs — a recurring new-data alert. State is kept in the actor's key-value store.", "default": false } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```