Get Beneficial Owners
secedgar_get_beneficial_ownersList the 5%-and-over beneficial owners of a public company, parsed from the structured SCHEDULE 13D and SCHEDULE 13G filings made about it. The input is the ISSUER — the company being held — which is the opposite direction from secedgar_get_institutional_holdings, where the input is the manager. 13D is the activist form and carries the filer's stated purpose of the transaction; 13G is the passive form and has no purpose field at all, which is the substantive difference between a stake that intends to influence control and one that does not. Every filing is returned with each reporting person listed separately, because voting power, dispositive power, and percent of class are reported per person even on a joint filing where several funds and their controlling principal report overlapping shares — summing those percentages double-counts the same position. Coverage starts at 2024-12-18, when SEC replaced the legacy SC 13D / SC 13G text filings with this XML format; earlier stakes are readable but not parseable, and the response reports how many of them the issuer has. The full parsed set is materialized as df_ when a canvas is available, one row per reporting person, so it joins against the insider and 13F dataframes on issuer CIK.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of filings to fetch and parse, newest first. Each filing is a separate document fetch, so this is the cost of the call as well as its depth. Default 10; a widely-held company can have dozens of blockholder filings a year. | |
| issuer | Yes | The company whose blockholders you want — a ticker ("AAPL"), a 10-digit CIK ("0000320193"), or a company name. This is the subject company of the schedule, not the investor filing it; passing an investment manager here returns the schedules filed about that manager, which is almost always empty. | |
| form_kind | No | Which schedule to return. "13D" is the activist form, filed by a holder that may seek to influence control and carrying a stated purpose of transaction. "13G" is the passive form, available to institutions and holders under 20% that certify no control intent. "all" (default) returns both, newest first. | all |
| include_amendments | No | Whether to include amendments (SCHEDULE 13D/A, SCHEDULE 13G/A). Amendments carry the current position and are how an ongoing stake is tracked, so they are included by default. Set false to see only filings that opened a new position. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The limit cap applied. | |
| error | No | Present when the call failed. Absent on success. | |
| shown | No | Number of filings returned. | |
| issuer | No | The issuer input, echoed. | |
| notice | No | Guidance when no filings matched — names the coverage boundary and the fallback. | |
| dataset | No | Canvas dataframe holding one row per reporting person across every parsed filing, each row carrying the issuer, form, accession, and dates alongside the person's powers. Joins against the insider and 13F dataframes on issuer_cik. Absent when canvas is unavailable or nothing parsed. | |
| filings | No | Blockholder filings, newest first, capped at limit. | |
| form_kind | No | The schedule filter applied — the requested value, or the default "all". | |
| truncated | No | True when filings were capped by limit. | |
| issuer_cik | No | CIK of the resolved issuer, zero-padded to 10 digits. | |
| issuer_name | No | EDGAR-conformed name of the resolved issuer. | |
| filings_parsed | No | Filings actually fetched and parsed — total_structured_filings capped by limit. | |
| structured_coverage_from | No | First filing date on which SEC required this XML format (YYYY-MM-DD). Blockholder filings before it exist but are not parseable into this schema. | |
| total_structured_filings | No | Structured SCHEDULE 13D/13G filings matching the form filter in the issuer's recent submissions window, before the limit. The population the returned filings are the newest slice of. | |
| legacy_filings_before_coverage | No | Legacy SC 13D / SC 13G filings in the issuer's recent submissions window — pre-2024-12-18 stakes this tool cannot parse. Reach them with secedgar_search_filings and read them with secedgar_get_filing. A floor, not a lifetime count: the submissions window holds roughly the last thousand filings of every type. |