get_owner_list
TOOLGet owner listscope: dataflow:ownership.read · read-only
Tool description, as exposed to the agent
Returns the largest shareholders of a publicly listed company, ordered by percentage of total share capital owned (largest first). Each row reflects the most recent verified ownership data for that owner (see valid_from). Use search_securities first to obtain the company_id. Two perspectives are supported: 'beneficial' (who ultimately benefits, e.g. an individual or family who owns through holding companies) and 'manager' (which fund manager or asset manager directly controls the position). Each owner row reports total shares held, fraction of capital, fraction of voting rights (which can differ from capital because of multi-class share structures), whether sub-holdings exist beneath the owner (has_sub_holdings, drillable via get_sub_holdings), and optionally a per-stock breakdown across share classes. The list can span more than one page (default limit 25, max 100 per page); when next_cursor is present in the response, pass it back as cursor on the next call to retrieve the next page until next_cursor is absent. Successful calls may consume Dataflow credits per owner row actually returned; nested stock breakdowns do not add units, and an empty result costs zero credits.Parameters
| Parameter | Type | Description | |
|---|---|---|---|
| company_id | integer | required | The Modular Finance internal company_id from search_securities. Do not pass ISIN, LEI, or ticker symbols here. Nonzero integer; the sign of the ID has NO meaning; negative IDs are normal and are NOT a flag for 'unlisted', 'private', or anything else. Pass it through verbatim. |
| mode | 'beneficial' | 'manager' | optional | 'beneficial' attributes shares to the ultimate beneficial owner. 'manager' attributes shares to the nearest visible fund or asset manager.default "beneficial" |
| limit | integer | optional | Maximum number of owners per page. Owners are ordered by capital share descending. Hard cap 100. For full enumeration set limit=100 and page via cursor.default 25 · min 1 · max 100 |
| cursor | string | optional | Opaque pagination token returned as next_cursor by a prior call. Omit on the first call; pass back verbatim to retrieve the next page until next_cursor is absent. Must accompany identical company_id, mode, limit, min_capital, and include_stock_holdings values.max length 512 |
| min_capital | number | optional | Optional minimum capital ownership share, fraction 0-1 (0.001 = 0.1%, 0.05 = 5%).min 0 · max 1 |
| include_stock_holdings | boolean | optional | When true, each owner row includes a per-stock breakdown across share classes.default true |
Billing
Pricing keys: owner_list.beneficial, owner_list.manager. Successful calls consume Dataflow credits per your contract. See Credits & pricing.