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. Rows also carry the owner's place in its ownership chain and how it invests: owner_parent_id / owner_parent_name name the entity one level up (a fund family or manager) and are absent for a top-level owner, so their presence is how you tell a sub-fund from a parent without another call; management_type classifies the investment approach (active, passive, quantitative) and management_style refines it - pass underlying_management_type to count only the sub-funds of a given approach toward each owner's stake, which answers "how much of this register is passive money" but re-weights every fraction it returns (the response echoes the filter back); cost_basis with cost_basis_currency is the owner's average acquisition cost per share, blended across share classes, directly comparable to a share price. These four are omitted where the data is not available for a row. 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. Market convention differs by market: for UK (GB) companies the standard perspective is 'manager', for Nordic companies (SE, NO, DK, FI, IS) it is 'beneficial'. Defaults to your organisation's configured perspective ('beneficial' unless configured otherwise).default "beneficial" |
| adjust_treasury | boolean | optional | Denominator behind every capital and votes fraction in the response. false computes them on total issued shares, including any treasury shares the company holds itself, which is the Nordic standard. true computes them on shares outstanding, excluding treasury shares, which is the UK standard and makes the same holding read slightly higher. Defaults to your organisation's configured basis (unadjusted unless configured otherwise). get_shares_outstanding reports both share counts whatever you pass here.default false |
| 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 |
| underlying_management_type | string[] | optional | Optional restriction to one management sleeve. This does NOT simply drop owners - it changes what each one reports: only underlying funds carrying one of these classifications are rolled up, so each owner's shares, capital and votes become that sleeve's rather than the owner's whole stake. Use it for "how much of this is passive money"-shaped questions, not to look up a classification. Three consequences to expect: holdings not composed of classified sub-funds (individuals, companies holding directly) disappear entirely; an unclassified relationship counts as 'unknown', so asking for 'active' excludes it; and the response echoes the filter back, which is the only thing marking these numbers as sleeve-restricted. To read one fund's own classification instead, drill in with get_sub_holdings, whose management_type filter selects rows without touching their numbers.max items 4 |
| underlying_management_style | string[] | optional | Optional restriction to underlying funds carrying one of these style labels (e.g. 'growth', 'quality', 'index', 'thematic', 'no-style'), with the same re-aggregating semantics as underlying_management_type; giving both requires a fund to match both. The style vocabulary is curated rather than fixed, so an unrecognised value yields an empty result rather than an error.max items 32 |
| include_stock_holdings | boolean | optional | When true, each owner row includes a per-stock breakdown across share classes.default true |
| currency | string | optional | Optional ISO 4217 currency code (e.g. 'GBP', 'USD', 'SEK') to convert cost_basis into. Omit it and each cost_basis is reported in the currency that share class trades in, which is the currency directly comparable to the share price; cost_basis_currency names it either way. Pass a code only when you are comparing owners' costs across markets. |
Billing
Pricing keys: owner_list.beneficial, owner_list.manager. Successful calls consume Dataflow credits per your contract. See Credits & pricing.