# SEC Insider Cluster-Buy Watchdog (`hllerdgn80/sec-insider-cluster-buy-watchdog`) Actor

Scans official SEC EDGAR Form 4 filings for open-market insider purchases and flags cluster buys - multiple different insiders buying the same stock within a tight window - with a 0-100 conviction score.

- **URL**: https://apify.com/hllerdgn80/sec-insider-cluster-buy-watchdog.md
- **Developed by:** [Halil Erdogan](https://apify.com/hllerdgn80) (community)
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.01 / 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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## SEC Insider Cluster-Buy Watchdog

Scans a company's official SEC EDGAR Form 4 filings and flags **cluster
buys**: multiple *different* company insiders (executives, directors, 10%
owners) buying stock on the open market within a tight window of each
other. That pattern — several people with inside knowledge independently
choosing to buy at the same time — is a far stronger signal than any one
executive's purchase, and it's the one thing every other Form 4 Actor on
the Store skips: they list recent filings; this one scores them.

No API key, no scraping, no third-party data vendor. Every field traces
back to one of three official, free SEC endpoints:

- `sec.gov/files/company_tickers.json` — SEC's own ticker → CIK map
- `sec.gov/cgi-bin/browse-edgar?...&type=4&output=atom` — a company's Form 4 filing index
- the `form4.xml` ownership document for each filing

SEC's Fair Access policy asks automated callers to send a descriptive
`User-Agent` with a real contact email on every request — there is no key
to register. Put your email in the `contactEmail` input field and this
Actor sends it only to sec.gov, as SEC itself asks.

### What you get

One dataset row per watched ticker/CIK:

```json
{
  "identifier": "XYZ",
  "cik": "0001234567",
  "ticker": "XYZ",
  "issuer_name": "Example Corp",
  "found": true,
  "form4_filings_scanned": 12,
  "buy_transactions_in_window": 3,
  "cluster_detected": true,
  "conviction_score": 78,
  "distinct_insiders": 3,
  "insider_names": ["Doe Jane", "Roe John", "Smith Pat"],
  "window_start": "2026-09-10",
  "window_end": "2026-09-16",
  "span_days": 6,
  "total_shares": 42000,
  "total_value_usd": 1850000.0,
  "officer_or_director_count": 2,
  "ten_percent_owner_count": 1,
  "transaction_count": 3,
  "buy_events_in_cluster": [ /* one entry per qualifying transaction */ ]
}
```

`conviction_score` (0-100) combines: how many distinct insiders bought,
what fraction were officers/directors, the total dollar size, and how
tight the buying window was relative to the window you allowed.

### Input

| Field | Description |
|---|---|
| `watchlist` | Tickers (e.g. `"AAPL"`) or raw CIK numbers to watch. Required. |
| `contactEmail` | Your email, sent only to sec.gov in the User-Agent header, per SEC's own Fair Access request. |
| `lookbackDays` | Only purchases dated within this many days count. Default 30. |
| `clusterWindowDays` | Max span between the earliest and latest buy in a cluster. Default 10. |
| `minClusterInsiders` | Minimum distinct insiders required to call it a cluster. Default 2. |
| `maxFilingsToScanPerIssuer` | How many of the issuer's most recent Form 4 filings to pull. Default 40. |

### Why this matters

A single insider's open-market purchase is noisy — it can mean anything
from a scheduled plan to personal conviction. Several *different*
insiders buying independently, within days of each other, with no shared
grant or plan behind it, is the pattern professional insider-tracking
services charge subscriptions to surface. This Actor computes it directly
from SEC's own free filings, on your own schedule, with no subscription
and no key.

### Notes

- Only non-derivative, open-market purchases (Form 4 transaction code
  `P`, shares acquired) are counted toward a cluster. Option exercises,
  gifts, and sales are parsed but excluded from the cluster signal by
  design.
- SEC EDGAR is a free public service with no published rate-limit key,
  but the Actor paces its own requests conservatively and retries
  transient failures (429/5xx/connection resets) automatically.

# Actor input Schema

## `watchlist` (type: `array`):

Companies to check for insider cluster buys, one per entry: a stock ticker (e.g. "AAPL") or a raw SEC CIK number (e.g. "320193"). Tickers are resolved against SEC's own free, public company_tickers.json map - no third-party ticker database.

## `contactEmail` (type: `string`):

SEC's Fair Access rules ask every automated caller to send a descriptive User-Agent with a real contact address on each request (no API key is required or exists for these endpoints). Put your own email here; it is sent only to sec.gov as part of that header, never anywhere else.

## `lookbackDays` (type: `integer`):

Only open-market purchase transactions (Form 4 transaction code "P", shares acquired) dated within this many days of today are considered when looking for a cluster.

## `clusterWindowDays` (type: `integer`):

A 'cluster buy' is multiple distinct insiders each buying on the open market within this many days of one another. This is the Actor's core signal: the tightest window inside the lookback period that contains the most distinct buyers is reported as the cluster.

## `minClusterInsiders` (type: `integer`):

An issuer is only flagged cluster_detected when at least this many DIFFERENT reporting owners (not the same person filing twice) bought within the cluster window.

## `maxFilingsToScanPerIssuer` (type: `integer`):

How many of the issuer's most recent Form 4 filings to pull from EDGAR's index and parse. Raise this for very active issuers if the lookback window needs more history than the default covers.

## Actor input object example

```json
{
  "watchlist": [
    "AAPL",
    "MSFT"
  ],
  "lookbackDays": 30,
  "clusterWindowDays": 10,
  "minClusterInsiders": 2,
  "maxFilingsToScanPerIssuer": 40
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "watchlist": [
        "AAPL",
        "MSFT"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("hllerdgn80/sec-insider-cluster-buy-watchdog").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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "watchlist": [
        "AAPL",
        "MSFT",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("hllerdgn80/sec-insider-cluster-buy-watchdog").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "watchlist": [
    "AAPL",
    "MSFT"
  ]
}' |
apify call hllerdgn80/sec-insider-cluster-buy-watchdog --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,hllerdgn80/sec-insider-cluster-buy-watchdog"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/5xkz9vHIrrT8cBTJr/builds/Ddl93AnNlhEle2jGs/openapi.json