Methodology
Every record is read from a filing at the SEC, and some fields are not in the filing as such: a ticker, a currency, a role, whether a trade was planned. This page explains how we arrive at them and where we leave a value empty rather than guess. The endpoint reference has the exact definition of every field; this page explains the decisions behind them.
Which forms each area reads
- Insider transactions (
/insider): Form 4, Form 5 and their amendments, Form 4/A and 5/A. - Material events (
/events): Form 8-K and 8-K/A, plus NT 10-K and NT 10-Q as events of typelate_filing. - Institutional holdings (
/institutional): Form 13F-HR, 13F-HR/A and 13F-NT.
What each form reports and how quickly it has to be filed is on the data sources page.
Timestamps
filed_at is the time the SEC accepted the filing, in US Eastern Time with its offset, because that is the time zone the SEC reports in. Filings we receive as they are published carry that time to the second. For older filings loaded from the SEC’s historical archives, the archive gives only the date; we add the acceptance time from the SEC afterwards where the SEC provides it, and otherwise the value stays at midnight of the filing day. Read a midnight filed_at as “some time on that day”.
transaction_date and event_date are the dates the filer states for the trade or the event. They often lie days before filed_at: a Form 4 may be filed two business days after the trade, a Form 5 months later. For a backtest, decide on filed_at when you could have known, not on the trade date.
Amendments
- Form 4/A and 5/A are kept as rows of their own next to the original, which stays unchanged. An amendment usually repeats the whole filing, so do not add an original and its amendment together. It names the date of the filing it corrects, in
original_filed_on, but not its accession number; match the original by issuer, insider and that date. Cluster buys and the officer buy/sell ratio count originals only. - Form 8-K/A runs through the same normalisation as an 8-K and appears as an event of its own.
- Form 13F-HR/A is applied to the quarter: a restatement replaces the portfolio we hold for that quarter, an amendment that adds holdings is added to it. An original that arrives after its own restatement does not overwrite it.
Tickers
A filing identifies the company by its CIK, the SEC’s company number; the ticker typed into a Form 4 is free text. For insider transactions we therefore take the ticker from the SEC’s official list of companies whenever the CIK is in it. Where the SEC lists several tickers for one company — common stock, warrants, preferred shares, notes — we use the first one in the SEC’s list, which is the common stock. A company that is no longer in the list keeps the ticker from its filing.
An 8-K names its ticker on the cover page, as of the day it was filed, and that takes precedence; the official list fills in only where the cover page names none. A ticker can change over the years, the CIK does not: filter by cik when you need a company’s full history.
Rule 10b5-1 plans
is_10b5_1 says whether a trade was made under a Rule 10b5-1 trading plan, set up in advance. Since April 2023 Form 4 has a checkbox for it, and that checkbox decides. For filings without it, a footnote that mentions Rule 10b5-1 marks the trade as planned. Without either, the field is null: not stated, which is not the same as “not planned”.
Prices and currencies
Form 4 has no currency field. A price is in US dollars unless the filing itself says otherwise: a footnote on the price that names another currency (for example CAD), or a security title that names a listing outside the US (for example BRL for preference shares traded in São Paulo). A footnote saying the price was converted into US dollars keeps USD; prices in pence are GBX.
price is null when the filing states none, typically when a trade consisted of several executions and the price is given in a footnote. A price of 0 is a real statement. Sums in US dollars — the value of a cluster buy, the capital in the officer ratio — leave out trades priced in another currency, but still count them as trades.
The cluster-buy rule
/insider/cluster-buys finds companies where at least min_insiders different insiders bought on the open market (code P) within the window. Each result names its rule in rule_version, and cluster-buys-v1 is:
- buyers are counted by name, the first reporting person of a filing; a joint filing counts as one buyer;
- the window filters the trade date and ends today, or at the end of
as_ofin Eastern Time — then only filings submitted by that point count; - Form 4 and Form 5 count, their amendments do not;
rolesrestricts the role of the first reporting person before anything is counted.
Each cluster also says whether its buyers acted together: uniform_price is true when at least three of them report a price and all bought at the same price. Insiders who buy on the same day at the same price usually did not decide independently — they took part in a private placement or an offering, or bought through a plan such as dividend reinvestment or fees paid in shares. Add exclude_uniform_price=true to leave such clusters out. Without it, the result is unchanged.
sec_known_at is the earliest filing time at which the threshold was reached. It is not the time this API delivered the cluster, and not a price you could have traded at. The exact definitions are in the reference for cluster buys.
What the data is not
algoum processes what companies and insiders report to the SEC. It does not check whether a filing is true, and a cluster buy or a ratio is a calculation, not a recommendation. Read the disclaimer before you trade on it.
Report a data discrepancy
If a record does not match the filing it came from, please tell us. Include the filing_id of the record and the meta.request_id of the response, and if you can, what the original filing says; then we can find both again.