# SEC Filing Change Detector – 10-K/10-Q Evidence API (`bb-tradetec/sec-filing-change-detector`) Actor Compare official SEC 10-K or 10-Q filings by canonical narrative section. Get deterministic change hunks, bounded old/new evidence, stable IDs, direct filing links, partial errors, and stateless cursors without AI summaries or materiality claims. - **URL**: https://apify.com/bb-tradetec/sec-filing-change-detector.md - **Developed by:** [BB](https://apify.com/bb-tradetec) (community) - **Categories:** Developer tools, News, Automation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $20.00 / 1,000 compared sec filings 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 web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. 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/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.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/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 ## SEC Filing Change Detector – 10-K/10-Q Evidence API Compare two official SEC filings by canonical narrative section and receive a deterministic, evidence-backed change record. The Actor is designed for due diligence agents, disclosure monitoring, and reproducible filing pipelines. One successful default-dataset row is one complete filing comparison and one `apify-default-dataset-item` pay-per-event result. Sections and change hunks are nested inside that row; `SUMMARY` and `ERRORS` are free KVS records. ### What it returns - Canonical 10-K and 10-Q sections such as Risk Factors, MD&A, Controls, Cybersecurity, Legal Proceedings, Business, and Market Risk. - Stable old/new filing metadata, content hashes, direct SEC document and filing-index links, paragraph anchors, bounded evidence, and truncation counts. - Deterministic `added`, `removed`, and `modified` hunks from `sec-section-diff.v1`; no embeddings or LLM. - Exact accession-pair mode and three baseline rules: comparable prior period, immediately prior root-form filing, or amendment-to-original. - Partial errors and optional client-carried stateless cursors. ### Quick start ```json { "queries": [ { "requestId": "apple-risk-yoy", "identifierType": "ticker", "identifier": "AAPL" } ], "forms": ["10-K"], "sections": ["risk_factors", "mda", "controls"], "comparisonBasis": "previous_comparable_period", "maxComparisons": 1 } ```` Ticker matches are exact and case-insensitive. CIKs may omit leading zeroes. Company names match exactly after case and whitespace normalization. An exact pair uses `identifierType: "accessionNumber"`, the new accession in `identifier`, plus issuer `cik` and `baselineAccessionNumber`. ### Comparison semantics - `previous_comparable_period`: 10-K uses the immediately prior non-amended 10-K. 10-Q uses the same fiscal-quarter report period in the prior year; no silent sequential fallback occurs. - `previous_filing`: immediately prior filing of the same root form. A 10-Q from another fiscal quarter is explicitly labeled `sequential_not_same_fiscal_period`. - `amendment_original`: only an amendment with exactly one non-amended filing of the same root form and report period. - Explicit accessions: both filing indices are loaded and issuer, accession, root form, dates, and primary documents are validated. ### Limits and costs Input is limited to 10 queries, 7 unique sections, 20 inspected filing metadata rows per company query, and 10 unique comparisons. Primary documents are capped at 15 MB each, document downloads at 120 MB per run, visible text at 2 million characters per document, and one section at 500,000 characters. Evidence is 500–5,000 characters per old/new side; hunk counts before and after limits stay visible. Planned pricing is `$0.00005` per Actor start and `$0.02` per comparison, but this local project is not published or monetized. Actual pricing is only real when the Actor API and Store show it. ### Source, limitations, and privacy The Actor uses the SEC ticker catalog, submissions JSON, filing-detail pages, and visible primary-document content under the official SEC archive. SEC data is filer-reported and may contain errors. Section extraction is deterministic but HTML structures vary, and table text is narrative evidenceβ€”not normalized financial facts. `changeRatio` measures text change; it is not a materiality, risk, sentiment, legal, bullish, or bearish score. The Actor does not provide investment advice, AI summaries, XBRL financial comparisons, full-text search, or completeness guarantees. It is independent and not affiliated with or endorsed by the U.S. Securities and Exchange Commission. There is no publisher-side filing database, persistent cache, watchlist, browser automation, user secret, or Standby endpoint. Do not put personal data, email addresses, or secrets in `requestId`. See the complete [public interface](docs/product/interface.md) and [implementation specification](docs/implementation-spec.md). # Actor input Schema ## `queries` (type: `array`): Use unique requestId values. Accession queries require cik and baselineAccessionNumber. Do not place secrets, email addresses, or personal text in requestId. ## `forms` (type: `array`): 10-K and/or 10-Q. Amendments follow includeAmendments. ## `sections` (type: `array`): Unsupported sections are never reinterpreted. They produce explicit warnings; a pair with no selected section on either side produces no charged row. ## `comparisonBasis` (type: `string`): Comparable prior-year period, immediately prior root-form filing, or original for amendments. Explicit accession pairs are reported as explicit\_accessions. ## `includeAmendments` (type: `boolean`): When false, amendments cannot be selected as the new filing. ## `filedFrom` (type: `string`): Inclusive YYYY-MM-DD. ## `filedTo` (type: `string`): Inclusive YYYY-MM-DD. ## `includeUnchangedSections` (type: `boolean`): Unchanged sections are always counted; enable to include their section objects. ## `evidenceMaxChars` (type: `integer`): Hard maximum for each returned old or new hunk excerpt. ## `maxChangeHunksPerSection` (type: `integer`): Hard returned-hunk limit; full pre-limit counts remain visible. ## `maxComparisons` (type: `integer`): Hard run output and pay-per-event bound. ## `outputMode` (type: `string`): compact omits long evidence bodies while retaining hashes, anchors, counts, and short changed token ranges. ## `outputSchemaVersion` (type: `string`): Explicit executable output contract version. ## `incremental` (type: `object`): First run: use an empty object. Continuations: copy SUMMARY.nextCursor unchanged. Explicit accession pairs are incompatible. ## Actor input object example ```json { "queries": [ { "requestId": "apple-risk-yoy", "identifierType": "ticker", "identifier": "AAPL" } ], "forms": [ "10-K" ], "sections": [ "risk_factors", "mda", "controls" ], "comparisonBasis": "previous_comparable_period", "includeAmendments": false, "includeUnchangedSections": false, "evidenceMaxChars": 2000, "maxChangeHunksPerSection": 50, "maxComparisons": 5, "outputMode": "full", "outputSchemaVersion": "1.0" } ``` # Actor output Schema ## `comparisons` (type: `string`): Default dataset. Each row is one complete, unique filing comparison and one filing-comparison PPE event. ## `summary` (type: `string`): Non-chargeable SUMMARY record with counts, limits, warning counts, bytes, and optional next cursor. ## `errors` (type: `string`): Non-chargeable ERRORS record. Successful comparison rows remain available when another query or filing fails. # 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 = {}; // Run the Actor and wait for it to finish const run = await client.actor("bb-tradetec/sec-filing-change-detector").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 = {} # Run the Actor and wait for it to finish run = client.actor("bb-tradetec/sec-filing-change-detector").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 '{}' | apify call bb-tradetec/sec-filing-change-detector --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=bb-tradetec/sec-filing-change-detector", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "SEC Filing Change Detector – 10-K/10-Q Evidence API", "description": "Compare official SEC 10-K or 10-Q filings by canonical narrative section. Get deterministic change hunks, bounded old/new evidence, stable IDs, direct filing links, partial errors, and stateless cursors without AI summaries or materiality claims.", "version": "0.1", "x-build-id": "cXff4szdeY6GHi5cc" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/bb-tradetec~sec-filing-change-detector/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-bb-tradetec-sec-filing-change-detector", "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/bb-tradetec~sec-filing-change-detector/runs": { "post": { "operationId": "runs-sync-bb-tradetec-sec-filing-change-detector", "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/bb-tradetec~sec-filing-change-detector/run-sync": { "post": { "operationId": "run-sync-bb-tradetec-sec-filing-change-detector", "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", "required": [ "queries" ], "properties": { "queries": { "title": "Issuer or explicit filing-pair queries", "minItems": 1, "maxItems": 10, "type": "array", "description": "Use unique requestId values. Accession queries require cik and baselineAccessionNumber. Do not place secrets, email addresses, or personal text in requestId.", "items": { "type": "object", "additionalProperties": false, "required": [ "requestId", "identifierType", "identifier" ], "properties": { "requestId": { "title": "Request ID", "description": "Stable caller correlation ID returned in requestIds.", "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$" }, "identifierType": { "title": "Identifier type", "description": "Exact issuer lookup type or exact new-filing accession.", "type": "string", "enum": [ "ticker", "cik", "companyName", "accessionNumber" ] }, "identifier": { "title": "Ticker, CIK, exact company name, or new accession", "description": "Bounded exact identifier; no fuzzy matching is performed.", "type": "string", "minLength": 1, "maxLength": 200 }, "cik": { "title": "Issuer CIK for explicit accessions", "description": "Required issuer CIK only for accessionNumber queries.", "type": "string", "pattern": "^\\d{1,10}$" }, "baselineAccessionNumber": { "title": "Baseline accession for explicit pair", "description": "Exact old accession required only for accessionNumber queries.", "type": "string", "pattern": "^\\d{10}-\\d{2}-\\d{6}$" } } }, "default": [ { "requestId": "apple-risk-yoy", "identifierType": "ticker", "identifier": "AAPL" } ] }, "forms": { "title": "Root forms", "minItems": 1, "maxItems": 2, "uniqueItems": true, "type": "array", "description": "10-K and/or 10-Q. Amendments follow includeAmendments.", "items": { "type": "string", "pattern": "^10-[KQ]$" }, "default": [ "10-K" ] }, "sections": { "title": "Canonical sections", "minItems": 1, "maxItems": 7, "uniqueItems": true, "type": "array", "description": "Unsupported sections are never reinterpreted. They produce explicit warnings; a pair with no selected section on either side produces no charged row.", "items": { "type": "string", "pattern": "^(business|risk_factors|cybersecurity|legal_proceedings|mda|market_risk|controls)$" }, "default": [ "risk_factors", "mda", "controls" ] }, "comparisonBasis": { "title": "Baseline rule", "enum": [ "previous_comparable_period", "previous_filing", "amendment_original" ], "type": "string", "description": "Comparable prior-year period, immediately prior root-form filing, or original for amendments. Explicit accession pairs are reported as explicit_accessions.", "default": "previous_comparable_period" }, "includeAmendments": { "title": "Include 10-K/A and 10-Q/A as new filings", "type": "boolean", "description": "When false, amendments cannot be selected as the new filing.", "default": false }, "filedFrom": { "title": "New filing filed from", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Inclusive YYYY-MM-DD." }, "filedTo": { "title": "New filing filed to", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Inclusive YYYY-MM-DD." }, "includeUnchangedSections": { "title": "Return unchanged sections", "type": "boolean", "description": "Unchanged sections are always counted; enable to include their section objects.", "default": false }, "evidenceMaxChars": { "title": "Evidence characters per old/new side", "minimum": 500, "maximum": 5000, "type": "integer", "description": "Hard maximum for each returned old or new hunk excerpt.", "default": 2000 }, "maxChangeHunksPerSection": { "title": "Maximum hunks per section", "minimum": 1, "maximum": 200, "type": "integer", "description": "Hard returned-hunk limit; full pre-limit counts remain visible.", "default": 50 }, "maxComparisons": { "title": "Maximum unique comparison rows", "minimum": 1, "maximum": 10, "type": "integer", "description": "Hard run output and pay-per-event bound.", "default": 5 }, "outputMode": { "title": "Output mode", "enum": [ "full", "compact" ], "type": "string", "description": "compact omits long evidence bodies while retaining hashes, anchors, counts, and short changed token ranges.", "default": "full" }, "outputSchemaVersion": { "title": "Output schema version", "enum": [ "1.0" ], "type": "string", "description": "Explicit executable output contract version.", "default": "1.0" }, "incremental": { "title": "Stateless incremental mode", "type": "object", "description": "First run: use an empty object. Continuations: copy SUMMARY.nextCursor unchanged. Explicit accession pairs are incompatible.", "properties": { "cursor": { "title": "Previous cursor", "description": "Opaque nextCursor copied unchanged from the prior SUMMARY.", "type": "string", "maxLength": 32768, "pattern": "^secchgcur1_[A-Za-z0-9_-]+$" } }, "additionalProperties": 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 } } } } } } } } } } ```