Building an AI agent? Start with /llms.txt for the full site index.
Capital Flows
Per-ticker daily institutional positioning: foreign / investment-trust / dealer net buys and their total, foreign ownership % and its percentile, buy/sell streaks, and institutional share of volume. Derived from the foreign-holding + institutional-flow families. Not a forecast, not a recommendation.
GET /v2/datasets/institutional-positioningThis dataset is in build and not yet queryable via the API. The coverage and honest limitations below are the real database state; it moves off "Building" once serving lands (targeted 8/1).
| Field | Type | Description |
|---|---|---|
foreign_net_buy | shares | |
investment_trust_net_buy | shares | |
dealer_net_buy | shares | |
institutional_net_buy_total | shares | |
foreign_pct | ratio | |
foreign_pct_percentile | ratio | within-history rank, NOT a rating |
buy_streak | days | |
sell_streak | days | |
inst_share_of_volume | ratio | NULL where volume absent |
Per-ticker daily from ~2013 (first sample 2013-01-11). foreign_pct_percentile is a within-history rank coordinate (not a rating). inst_share_of_volume NULL where volume is unavailable. This is a heavy aggregation VIEW — serving should be ticker+date-bounded (full scans time out).
A real response from this endpoint. Rows are returned under "data", and provenance is carried in the shape shown below — it is not identical across datasets, so read this page's rather than assuming another's.
{ "dataset_id": "institutional-positioning", "row_count": 3, "data": [ { "ticker": "2330", "market": "TWSE", "trade_date": "2026-07-16", "foreign_net_buy": -4214736.0, "investment_trust_net_buy": 528374.0, "dealer_net_buy": 1061380.0, "institutional_net_buy_total": -2624982.0, "foreign_pct": null, "foreign_pct_percentile": null, "buy_streak": 0, "sell_streak": 6 }, { "ticker": "2330", "market": "TWSE", "trade_date": "2026-07-15", "foreign_net_buy": -3427281.0, "investment_trust_net_buy": -596431.0, "dealer_net_buy": 455841.0, "institutional_net_buy_total": -3567871.0, "foreign_pct": null, "foreign_pct_percentile": null, "buy_streak": 0, "sell_streak": 5 }, { "ticker": "2330", "market": "TWSE", "trade_date": "2026-07-14", "foreign_net_buy": -12416209.0, "investment_trust_net_buy": 1841069.0, "dealer_net_buy": 2569779.0, "institutional_net_buy_total": -8005361.0, "foreign_pct": 69.54, "foreign_pct_percentile": 0.105088, "buy_streak": 0, "sell_streak": 4 } ]}Captured from the live API on 2026-07-20.
curl "https://api.twmarketdata.com/v2/datasets/institutional-positioning?symbol=2330" \ -H "X-API-Key: sk_live_..."| Parameter | Required | Type | Description |
|---|---|---|---|
symbol | Yes | string | Ticker, e.g. 2330. |
start_date | No | string (YYYY-MM-DD) | Start of the query range. |
end_date | No | string (YYYY-MM-DD) | End of the query range. |
limit | No | integer | Maximum rows to return. |
A first call:
import requests resp = requests.get( "https://api.twmarketdata.com/v2/datasets/institutional-positioning", params={"symbol": "2330"}, headers={"X-API-Key": "sk_live_..."},)resp.raise_for_status()print(resp.json()["data"])With a date-range filter:
import requests # The full verified example — the same call with every supported filter set.resp = requests.get( "https://api.twmarketdata.com/v2/datasets/institutional-positioning", params={"symbol": "2330"}, headers={"X-API-Key": "sk_live_..."},)resp.raise_for_status()for row in resp.json()["data"]: print(row)This endpoint is GET /v2/datasets/institutional-positioning. The full machine-readable schema (parameters, security, response envelope) lives in the OpenAPI spec.