# SEC 13F Position Deltas – Amendments & Evidence API (`bb-tradetec/sec-13f-position-delta-normalizer`) Actor Compare official SEC 13F manager-quarter snapshots with amendment-aware composition, full position keys, amount-based changes, stable IDs and filing evidence. - **URL**: https://apify.com/bb-tradetec/sec-13f-position-delta-normalizer.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 $4.00 / 1,000 computed 13f position deltas 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/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 13F Position Deltas – Amendments & Evidence API Turn official SEC Form 13F filings into deterministic quarter-over-quarter position changes. The Actor composes original `13F-HR` filings with supported `13F-HR/A` amendments, preserves the complete reported position key, and emits one dataset row per new, increased, decreased, exited, or unchanged position. This is an independent Community Actor. It is not affiliated with or endorsed by the U.S. Securities and Exchange Commission. ### What you get - exact investment-manager resolution by CIK, plus exact unique name lookup; - `previous_quarter`, `previous_available`, and explicit-accession comparisons; - amendment-aware `RESTATEMENT` and `NEW HOLDINGS` snapshot composition; - CUSIP, class, put/call, amount type, discretion, and other-manager references; - amount- and value-deltas, optional voting authority, stable record IDs; - direct SEC information-table URLs, accession manifests, and snapshot hashes; - bounded partial errors in `ERRORS` and run metrics/cursor in `SUMMARY`. No ticker is guessed from a CUSIP. Change direction is determined by reported share/principal amount, not by filing value. The output does not claim when or at what price a manager traded. ### Input example ```json { "queries": [ { "requestId": "berkshire-qoq", "identifierType": "managerCik", "identifier": "1067983" } ], "comparisonBasis": "previous_quarter", "deltaTypes": ["new", "increased", "decreased", "exited"], "includeVotingAuthority": true, "maxDeltas": 100, "outputMode": "full" } ```` `maxDeltas` is both a hard result bound and the future pay-per-result ceiling. Use `periodOfReport` to pin the current calendar-quarter end. Use `explicit_accessions` only with manager-CIK queries and both accession fields. ### Output unit Every default-dataset item is one unique position delta between two complete, canonical manager-quarter snapshots. Matching queries merge into `requestIds`. The reserved `apify-default-dataset-item` PPE event is therefore exactly one result unit and is emitted by the same dataset push after Cloud pricing is configured. The row includes: - `manager` and `comparison` snapshot identity; - full `security` position key, without inferred ticker; - `delta` amounts, values, percentage, and direction; - optional current voting authority; - original SEC document URLs, retrieval time, and warnings. ### Limits and data semantics - 1–10 manager queries, 1–2,000 output deltas; - at most 20 relevant filing records per manager/period; - 10 MB per information table and 120 MB total SEC data per run; - 10,000 raw positions per snapshot and 10 amendments across compared periods; - `13F NOTICE` and `13F COMBINATION REPORT` are rejected as incomplete; - official SEC HTTPS endpoints only, at most eight requests per second; - no publisher-side filing database, permanent cache, or watchlist. Form 13F is delayed, as-filed reporting and may contain filer errors. It does not reveal short positions or intraperiod trades. This Actor provides source normalization, not investment, legal, tax, or compliance advice. ### Storage contract - Default dataset: successful, chargeable position-delta rows only. - Dataset rows use a closed JSON Schema at every object level; `full` requires both snapshot manifests, while `compact` omits both and voting authority remains independently optional. - Default KVS `SUMMARY`: counts, limits, byte use, warnings, optional cursor. - Default KVS `ERRORS`: bounded query/document errors; successful batch parts remain available. ### Local development Requires Python 3.13. ```bash python3.13 -m venv .venv .venv/bin/pip install -e '.[dev]' source .venv/bin/activate pytest ruff check . mypy src apify run ``` See [`docs/implementation-spec.md`](docs/implementation-spec.md), [`docs/test-plan.md`](docs/test-plan.md), and [`docs/product/interface.md`](docs/product/interface.md) for the executable contract and release gates. # Actor input Schema ## `queries` (type: `array`): Use a manager CIK, an exact manager name, or explicit accessions with the manager CIK. ## `periodOfReport` (type: `string`): Optional calendar-quarter end; newest complete period by default. ## `comparisonBasis` (type: `string`): Immediate prior quarter, prior available complete period, or exact accessions. ## `deltaTypes` (type: `array`): Position-change directions to include: new, increased, decreased, exited, or unchanged. ## `includeUnchanged` (type: `boolean`): Add amount-unchanged positions to the result. ## `includeVotingAuthority` (type: `boolean`): Include current as-filed sole, shared, and none voting values. ## `minAbsoluteAmountChange` (type: `string`): Non-negative decimal string; does not alter direction. ## `minCurrentValueUsd` (type: `string`): Optional non-negative dollar value filter. ## `maxDeltas` (type: `integer`): Hard global dataset and future result-charge ceiling. ## `outputMode` (type: `string`): Compact preserves numeric values, hashes and sources. ## `outputSchemaVersion` (type: `string`): Published dataset contract. ## `incremental` (type: `object`): Copy SUMMARY.nextCursor unchanged for the next page. ## Actor input object example ```json { "queries": [ { "requestId": "berkshire-qoq", "identifierType": "managerCik", "identifier": "1067983" } ], "comparisonBasis": "previous_quarter", "deltaTypes": [ "new", "increased", "decreased", "exited" ], "includeUnchanged": false, "includeVotingAuthority": true, "minAbsoluteAmountChange": "0", "maxDeltas": 100, "outputMode": "full", "outputSchemaVersion": "1.0" } ``` # Actor output Schema ## `deltas` (type: `string`): Default dataset; exactly one amendment-aware 13F position delta per row. ## `summary` (type: `string`): Counts, warning totals and optional next cursor. ## `errors` (type: `string`): Bounded manager, filing and document errors. # 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-13f-position-delta-normalizer").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-13f-position-delta-normalizer").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-13f-position-delta-normalizer --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=bb-tradetec/sec-13f-position-delta-normalizer", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "SEC 13F Position Deltas – Amendments & Evidence API", "description": "Compare official SEC 13F manager-quarter snapshots with amendment-aware composition, full position keys, amount-based changes, stable IDs and filing evidence.", "version": "0.1", "x-build-id": "zIglRJLZrKsBTkRPh" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/bb-tradetec~sec-13f-position-delta-normalizer/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-bb-tradetec-sec-13f-position-delta-normalizer", "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-13f-position-delta-normalizer/runs": { "post": { "operationId": "runs-sync-bb-tradetec-sec-13f-position-delta-normalizer", "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-13f-position-delta-normalizer/run-sync": { "post": { "operationId": "run-sync-bb-tradetec-sec-13f-position-delta-normalizer", "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": "Manager queries", "minItems": 1, "maxItems": 10, "type": "array", "description": "Use a manager CIK, an exact manager name, or explicit accessions with the manager CIK.", "items": { "type": "object", "additionalProperties": false, "required": [ "requestId", "identifierType", "identifier" ], "properties": { "requestId": { "title": "Request ID", "description": "Caller-defined correlation ID returned in matching rows.", "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$" }, "identifierType": { "title": "Manager identifier type", "description": "Direct manager CIK or exact unique SEC manager name.", "type": "string", "enum": [ "managerCik", "managerName" ] }, "identifier": { "title": "Manager identifier", "description": "One-to-ten-digit manager CIK or exact manager name.", "type": "string", "minLength": 1, "maxLength": 200 }, "currentAccession": { "title": "Current accession", "description": "Required with explicit_accessions.", "type": "string", "pattern": "^\\d{10}-\\d{2}-\\d{6}$" }, "priorAccession": { "title": "Prior accession", "description": "Required with explicit_accessions.", "type": "string", "pattern": "^\\d{10}-\\d{2}-\\d{6}$" } } }, "default": [ { "requestId": "berkshire-qoq", "identifierType": "managerCik", "identifier": "1067983" } ] }, "periodOfReport": { "title": "Current quarter end", "pattern": "^\\d{4}-(03-31|06-30|09-30|12-31)$", "type": "string", "description": "Optional calendar-quarter end; newest complete period by default." }, "comparisonBasis": { "title": "Comparison basis", "enum": [ "previous_quarter", "previous_available", "explicit_accessions" ], "type": "string", "description": "Immediate prior quarter, prior available complete period, or exact accessions.", "default": "previous_quarter" }, "deltaTypes": { "title": "Delta types", "minItems": 1, "maxItems": 5, "uniqueItems": true, "type": "array", "description": "Position-change directions to include: new, increased, decreased, exited, or unchanged.", "items": { "type": "string", "pattern": "^(new|increased|decreased|exited|unchanged)$" }, "default": [ "new", "increased", "decreased", "exited" ] }, "includeUnchanged": { "title": "Include unchanged", "type": "boolean", "description": "Add amount-unchanged positions to the result.", "default": false }, "includeVotingAuthority": { "title": "Include voting authority", "type": "boolean", "description": "Include current as-filed sole, shared, and none voting values.", "default": true }, "minAbsoluteAmountChange": { "title": "Minimum absolute amount change", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "type": "string", "description": "Non-negative decimal string; does not alter direction.", "default": "0" }, "minCurrentValueUsd": { "title": "Minimum current filing value", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "type": "string", "description": "Optional non-negative dollar value filter." }, "maxDeltas": { "title": "Maximum deltas", "minimum": 1, "maximum": 2000, "type": "integer", "description": "Hard global dataset and future result-charge ceiling.", "default": 100 }, "outputMode": { "title": "Output mode", "enum": [ "full", "compact" ], "type": "string", "description": "Compact preserves numeric values, hashes and sources.", "default": "full" }, "outputSchemaVersion": { "title": "Output schema version", "enum": [ "1.0" ], "type": "string", "description": "Published dataset contract.", "default": "1.0" }, "incremental": { "title": "Stateless pagination", "type": "object", "description": "Copy SUMMARY.nextCursor unchanged for the next page.", "properties": { "cursor": { "title": "Previous cursor", "description": "Opaque client-carried cursor from SUMMARY.", "type": "string", "maxLength": 32768, "pattern": "^sec13fcur1_[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 } } } } } } } } } } ```