Owners & chains

An owner is any entity that holds equity: a pension fund, an asset manager, an institution, a holding company or an individual. Owners carry an owner_id, a name, a country and a type. Crucially, they also form chains.

Ownership is a tree, not a list

Real-world positions are layered. A family owns through a holding company; an asset manager's stake is the sum of dozens of individual funds; a pension fund reports through regional sub-entities. Dataflow preserves this structure:

• Owners can have a parent (parent_id), forming chains from the ultimate owner down to individual funds.
• A position can have sub-holdings: the positions reported underneath it by child entities.

Tier-one vs base

When you query holdings you choose the depth:

• Tier-one: one row per top-level owner, the view you'd print as "largest shareholders". Sub-structure is aggregated into the parent.
• Base: the full chain expanded, every reporting entity, including intermediate holding companies and individual funds.

On the REST side these are separate endpoints (…/tier-one and …/base). On the MCP side, tools return tier-one rows with a has_sub_holdings flag, and get_sub_holdings drills one level at a time, recursively, since each returned row may itself have children.

Reading the chain off a row

Every ownership row names the level directly above it: owner_parent_id and owner_parent_name. A row without them is a top-level owner, which makes their presence the test for "is this a sub-fund" - no extra call needed. This is on holdings, portfolio positions and ownership-change rows alike, so a move made by one fund can be attributed to the family it belongs to straight away.

Rows also carry how the owner invests, where Dataflow has classified it: management_type (active, passive, quantitative) and the finer-grained management_style. Both are omitted rather than guessed when there is no classification.

Finding owners

• MCP: search_owners resolves free-text names. By default it returns top-level entities; set only_top_level: false to include sub-entities.
• REST: filter any ownership endpoint by owner-ids, or pull an owner's whole portfolio by filtering on the owner side.