{ "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.2", "x-build-id": "pnru0MDr0PIWb2NaK" }, "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 ZIP files to pull, newest first. The SEC publishes two per month (first half / second half), so 6 covers roughly the last three months. NOTE: each file holds DAILY rows, and this same number is also used as the trailing-average window measured in OBSERVATIONS (trading days), unless you set Trailing window below.", "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 trailing average fails. Default 3 (a 3x jump). Lower = more sensitive. fails_spike is null, not false, when there is no prior history to compare against.", "default": 3 }, "includeShortInterest": { "title": "Include FINRA short interest", "type": "boolean", "description": "Also fetch and merge FINRA consolidated equity short interest, adding short_interest, short_interest_prev, days_to_cover, avg_daily_volume, market_class and their deltas. Settlement dates are resolved automatically from FINRA bi-monthly calendar (15th and month-end, rolled back to a business day) unless you supply them below. VERIFIED 2026-08-01: this file is CONSOLIDATED, not OTC-only - 12,745 of 22,209 records on 2026-06-30 were exchange-listed (NYSE, ARCA, Nasdaq NNM/SC, BZX, AMEX).", "default": false }, "shortInterestDates": { "title": "FINRA short-interest settlement dates (YYYY-MM-DD)", "type": "array", "description": "Optional. FINRA bi-monthly settlement dates to fetch, e.g. [\"2026-06-30\", \"2026-06-15\"]. LEAVE EMPTY to have the actor resolve the FINRA calendar itself (15th and month-end of each month, rolled back to a business day) across your lookback window. A date FINRA has not published returns HTTP 403 and is reported as not_published, not silently ignored.", "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. The series is sorted by symbol then date, so a cap on an all-symbols run returns an ALPHABETICAL subset - the run logs a TRUNCATED warning and stamps results_truncated=true on every row.", "default": 1000 }, "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 a NAMED key-value store (short-interest-ftd-monitor-state), keyed by your query scope, so it survives across runs. The first run for a given scope establishes the baseline and emits everything.", "default": false }, "trailingWindow": { "title": "Trailing-average window (observations)", "minimum": 0, "maximum": 250, "type": "integer", "description": "Number of prior daily observations used for the trailing average behind fails_spike and short_interest_spike. Leave at 0 to keep the historical behaviour, which reuses Lookback periods as the window. Set explicitly to decouple how much history you FETCH from how much you AVERAGE OVER.", "default": 0 } } }, "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 } } } } } } } } } }