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 1825 - five years), optionally ending on a past 'at' date; the window start may not fall more than five years before today. 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, reported in the currency that company's shares trade in and labelled by delta_value_currency - pass the optional currency argument to convert every row into one code instead), a change_type (new, increased, decreased or exited), whether sub-holdings exist beneath the position (has_sub_holdings, drillable via get_sub_holdings), and - where available - the owner's parent (owner_parent_id, owner_parent_name), so a move made by a single sub-fund can be attributed to its family, plus management_type and management_style. Pass underlying_management_type to see one management sleeve's move instead of the owner's whole move: only sub-funds of that approach are rolled up, so the stake, the delta and therefore the sort_by ranking are the sleeve's, and the response echoes the filter back. 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. 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 |
| days | integer | optional | Lookback window in calendar days, ending at 'at' (default today). e.g. 7 = last week, 90 = last quarter, 1825 = last five years. Default 30, max 1825 (five years). The window start may not fall more than five years before today, so a long window and a back-dated 'at' cannot be combined.default 30 · min 1 · max 1825 |
| 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' (the value of the share change). Largest movement first; rows from different markets are ranked against each other in a single currency, whatever currency each row is reported in.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 |
| underlying_management_type | string[] | optional | Optional restriction to one management sleeve. This does NOT simply drop positions - it changes what each one reports: only underlying funds carrying one of these classifications are rolled up, so each position's resulting stake and its delta become that sleeve's rather than the owner's whole move. Use it for "which passive money moved"-shaped questions, not to look up a classification. Three consequences to expect: owners 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. min_change and sort_by then rank the sleeve's delta, not the owner's.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_unlisted | boolean | optional | When true, includes changes in positions whose stocks are not currently publicly listed.default false |
| currency | string | optional | Optional ISO 4217 currency code (e.g. 'GBP', 'USD', 'SEK') to convert this response's money fields into. Omit it and each money field is reported in the currency that company's own shares trade in, which is the currency the figure is natively denominated in. Every money field is labelled with its own currency either way, so read that label rather than assuming one. Pass a code when you are comparing or adding up companies from different markets - that is the only case where a single currency is needed. |
Billing
Pricing keys: ownership.changes.beneficial, ownership.changes.manager. Successful calls consume Dataflow credits per your contract. See Credits & pricing.