list_portfolio_changes
TOOLList portfolio changesscope: dataflow:ownership.read · read-only
Tool description, as exposed to the agent
Lists the largest changes in one owner's equity portfolio over a recent period: which positions the owner built, trimmed, opened or closed, ranked by the size of the move. Use search_owners first to obtain the owner_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 company and the owner (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 company_id to narrow to this owner's change in a single 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 portfolio snapshot use get_owner_portfolio. Successful calls may consume Dataflow credits per change row actually returned; an empty result costs zero credits.Parameters
| Parameter | Type | Description | |
|---|---|---|---|
| owner_id | integer | required | Owner to report portfolio changes for. Rows are the companies where this owner moved its stake. 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. |
| company_id | integer | optional | Optional. Narrow to a single company: returns just how this owner's stake in THAT company changed. 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. |
| 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 owner.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 owner_id, company_id, mode, days, at, change_type, sort_by, min_change, and include_unlisted values.max length 512 |
| include_unlisted | boolean | optional | When true, includes changes in positions whose stocks are not currently publicly listed.default false |
Billing
Pricing keys: ownership.changes.beneficial, ownership.changes.manager. Successful calls consume Dataflow credits per your contract. See Credits & pricing.