list_owner_changes
TOOLList owner changesscope: dataflow:ownership.read · read-only
Tool description, as exposed to the agent
Lists the largest changes in who owns one company over a recent period: which owners built, trimmed, opened or closed a stake, ranked by the size of the move. Use search_securities first to obtain the company_id. The window is the last 'days' calendar days (default 30, max 365), optionally ending on a past 'at' date. Two perspectives are supported: 'beneficial' (the ultimate beneficial owner) and 'manager' (the nearest visible fund or asset manager). Each row reports the owner and the company (with their IDs), the resulting stake at the end of the window (capital, votes, shares), the change over the window (delta_capital, delta_shares, delta_votes and delta_value in USD), a change_type (new, increased, decreased or exited), and whether sub-holdings exist beneath the position (has_sub_holdings, drillable via get_sub_holdings). Pass an optional owner_id to narrow to a single owner's change in this company. Filter with change_type and min_change, rank with sort_by (capital or value). Results are returned a page at a time (default 20, max 50 per page); when next_cursor is present in the response, pass it back as cursor on the next call to page through all changes in the window until next_cursor is absent. For the current ownership snapshot use get_owner_list. Successful calls may consume Dataflow credits per change row actually returned; an empty result costs zero credits.Parameters
| Parameter | Type | Description | |
|---|---|---|---|
| company_id | integer | required | Company to report ownership changes for. Rows are the owners who moved their stake in this company. From search_securities. 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. |
| owner_id | integer | optional | Optional. Narrow to a single owner: returns just how THIS owner's stake in the company changed. From search_owners or an ownership tool. 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 positions to the ultimate beneficial owner. 'manager' attributes them to the nearest visible fund or asset manager. Must match the perspective used to discover the company.default "beneficial" |
| days | integer | optional | Lookback window in calendar days, ending at 'at' (default today). e.g. 7 = last week, 90 = last quarter. Max 365.default 30 · min 1 · max 365 |
| at | string | optional | Optional window END date (YYYY-MM-DD). Default today UTC. The window compared is [at − days, at]. |
| change_type | 'new' | 'increased' | 'decreased' | 'exited' | optional | Optional filter. 'new' = position opened in the window; 'increased'/'decreased' = existing position grew/shrank; 'exited' = position fully closed. Omit for all movement types. |
| sort_by | 'capital' | 'value' | optional | Rank by absolute change in 'capital' (fraction of share capital, default) or 'value' (USD value of the share change). Largest movement first.default "capital" |
| min_change | number | optional | Optional minimum ABSOLUTE change in capital ownership, fraction 0–1 (0.005 = 0.5 percentage points). Rows whose |delta_capital| is below this are dropped.min 0 · max 1 |
| limit | integer | optional | Maximum changes per page, ranked by sort_by descending. Hard cap 50.default 20 · min 1 · max 50 |
| cursor | string | optional | Opaque pagination token returned as next_cursor by a prior call. Omit on the first call; pass back verbatim to page through all changes WITHIN the same window until next_cursor is absent. Must accompany identical company_id, owner_id, mode, days, at, change_type, sort_by, and min_change values.max length 512 |
Billing
Pricing keys: ownership.changes.beneficial, ownership.changes.manager. Successful calls consume Dataflow credits per your contract. See Credits & pricing.