form4api

Python client for Form4API — real-time SEC Form 4 insider trading, Form 144 intent-to-sell, institutional 13F-HR, and congressional STOCK Act trading data, including the insider/Congress convergence signal.

Supports Python 3.11+. Uses httpx for both sync and async HTTP.

Installation

pip install form4api

Sync quickstart

from form4api import Form4ApiClient

client = Form4ApiClient("YOUR_API_KEY")

# Recent open-market purchases at Apple (excluding 10b5-1 plan trades)
txns = client.transactions.list(ticker="AAPL", code="P", exclude_10b5=True, per_page=5)
for t in txns:
    print(t.insider_name, t.insider_title, t.shares_amount, "@", t.price_per_share)
    print(f"  open market: {t.is_open_market}, 10b5 plan: {t.is10b5_plan}, value: ${t.total_value:,.0f}")

# Company overview (includes SIC, state, website)
company = client.companies.get("MSFT")
print(company.name, company.active_insiders, "active insiders")
print(company.sic_description, company.state_of_incorporation)

# Insider detail
insider = client.insiders.get("0001234567")
print(insider.name, insider.officer_title)

# Cluster-buy signals (Business plan)
signals = client.signals.list(cluster_buy=True)
for sig in signals:
    print(sig.company_name, sig.insider_count, "buyers on", sig.signal_date)

Async quickstart

import asyncio
from form4api import AsyncForm4ApiClient

async def main():
    async with AsyncForm4ApiClient("YOUR_API_KEY") as client:
        txns = await client.transactions.list(ticker="AAPL", per_page=5)
        for t in txns:
            print(t.insider_name, t.shares_amount, "@", t.price_per_share)

asyncio.run(main())

Resources

Congress date quality. Each congress trade (and convergence leg) has disclosure_lag_days: int | None and date_quality: str | None. When the filing's own dates are impossible or implausible, the lag is None and date_quality is one of "transaction_after_disclosure", "future_transaction_date" or "implausible_lag"; the raw dates are still returned. A lag over 45 days is not a legal finding.

for t in client.congress.trades(ticker="NVDA"):
    lag = f"dates unreliable ({t.date_quality})" if t.disclosure_lag_days is None else f"{t.disclosure_lag_days}d"
    print(t.politician.full_name, t.transaction_date, lag)

Every plan-gated endpoint the API exposes has a typed method here. Calling one your key isn't entitled to raises PlanError (HTTP 402) carrying required_plan, current_plan, and upgrade_url rather than failing opaquely.

An AsyncForm4ApiClient mirrors the whole surface with the same resources and method names — await client.insiders.leaderboard().

For the full parameter reference see the REST docs. For LLM workflows, form4api-mcp exposes the same endpoints as tools.

Transaction filters

client.transactions.list(
    ticker="AAPL",        # filter by ticker — accepts up to 25 comma-separated symbols
    cik="0000320193",     # or by company CIK
    insider_cik="...",    # filter by insider CIK
    code="P",             # transaction code: P=purchase, S=sale, A=grant, etc.
    from_date="2026-01-01",
    to_date="2026-12-31",
    filed_from="2026-01-01",  # filters on Filing.FiledAt (when it hit EDGAR), not the trade date
    filed_to="2026-12-31",
    exclude_10b5=True,    # omit trades filed under a Rule 10b5-1 plan
    per_page=100,
    page=1,
)

# Multi-ticker lookup in one call
client.transactions.list(ticker="AAPL,MSFT,NVDA")

Granular filtering (v0.4.0+)

# The "just show me real buys & sells" preset: open-market only,
# no 10b5-1 plan trades, no derivatives.
client.transactions.list(ticker="AAPL", significant=True)

# Multi-code include / exclude (comma-separated SEC codes)
client.transactions.list(codes="P,S")
client.transactions.list(exclude_codes="A,M,F,G")

# Whole-category filters: open_market | grants | derivatives | gifts | other
client.transactions.list(category="open_market")
client.transactions.list(exclude_category="derivatives")
client.transactions.list(exclude_derivative=True)

# Trade-size screening (Pro plan or higher)
client.transactions.list(min_value=1_000_000)          # USD, shares x price
client.transactions.list(min_shares=10_000, max_shares=100_000)

Transaction fields

Company fields

Search

client.search(q, limit=None) looks up companies and insiders by name or ticker in a single call — useful for a combined search box where you don't know in advance whether the user typed a ticker or a person's name. q must be 2-64 characters; outside that range the API returns HTTP 400 and the SDK raises Form4ApiError with error_code "QUERY_TOO_SHORT" or "QUERY_TOO_LONG". Insider matching is whitespace-tokenised, so "tim cook" matches an insider named "Cook Timothy D". limit caps the number of results per array (1-20, API default 8).

result = client.search("tim cook")
for c in result.companies:
    print(c.ticker, c.name, c.cik)
for i in result.insiders:
    # i.ticker is a ticker associated with the insider and may be None —
    # its exact meaning is still settling on the backend.
    print(i.cik, i.name, i.title, i.ticker)

Pagination

paginate() pages through the data until it runs out (a short or empty page) or, since the backend's 2026-08-01 plan-gated pagination depth (Free: 20 pages, Starter: 100, Pro+: unlimited), the next page is rejected with a 402. That 402 is not swallowed — it raises PaginationLimitError mid-iteration, after every page already yielded has been delivered to your loop. Pages you already received are real and complete; the error only means iteration stopped early. Pass max_pages to stop deliberately before that ever happens, or catch PaginationLimitError to know when a Free/Starter key ran out of depth on a bulk pull:

from form4api import PaginationLimitError

# transactions.paginate() — yields one list per page automatically
all_txns = []
try:
    for batch in client.transactions.paginate(ticker="NVDA", exclude_10b5=True, per_page=100):
        all_txns.extend(batch)
except PaginationLimitError as e:
    print(f"Stopped after {e.pages_yielded} pages — {e}")
    # all_txns still holds every page yielded before the limit hit

# signals.paginate()
all_signals = []
for batch in client.signals.paginate(cluster_buy=True, per_page=100, max_pages=10):
    all_signals.extend(batch)

Error handling

from form4api import (
    Form4ApiClient,
    AuthError,
    PlanError,
    PaginationLimitError,
    RateLimitError,
    NotFoundError,
)

client = Form4ApiClient("YOUR_API_KEY")

try:
    signals = client.signals.list()
except PaginationLimitError as e:
    print(f"Paginate stopped after {e.pages_yielded} pages — upgrade to go deeper")
except PlanError as e:
    print(f"Upgrade required")
except RateLimitError as e:
    print(f"Retry after {e.retry_after}s")
except AuthError:
    print("Invalid API key")
except NotFoundError:
    print("Resource not found")

License

MIT