Institutional Flows API

Overview

The Institutional Flows API provides access to SEC 13F-HR filing data, giving you visibility into what major institutional investors are doing with their portfolios. This data is sourced from mandatory SEC filings that institutions with over $100M in AUM must submit quarterly.

Use cases:

• Track aggregate buying/selling activity across all institutional filers
• See which institutions hold a specific stock and how their positions changed
• Monitor activist investors taking new or increased positions
• Analyze convertible bond activity for hedge fund arbitrage signals
• Track institutional options positioning (call vs put sentiment)
• Build quantitative strategies based on institutional flow signals

Filer categories: Each institutional filer is classified into one of 10 categories: INDEX_FUND, HEDGE_FUND, ACTIVIST, PENSION, BANK, INSURANCE, MUTUAL_FUND, SOVEREIGN_WEALTH, ENDOWMENT, OTHER.

Access: The /quarters endpoint is public. All other endpoints require a PRO subscription. Free/unauthenticated users see a limited preview (top 5 results for flows/holders, top 3 for other tabs) with isPreview: true in the response.

Important: Getting valid reportDate values

All institutional endpoints (except /quarters) require a reportDate parameter. Do not hardcode dates — available quarters change as new SEC filings are processed. Always call GET /quarters first to get valid dates:

# Step 1: Get available quarters
quarters = client.get_institutional_quarters()
latest_date = quarters[0]["reportDate"]  # e.g., "2025-12-31"

# Step 2: Use the reportDate in other calls
flows = client.get_institutional_flows(latest_date)
holders = client.get_stock_holders("AAPL", latest_date)

---

GET /quarters

Returns the list of available 13F reporting quarters with data.

Authentication: None required

Parameters: None

Example Request:

curl https://app.sentisense.ai/api/v1/institutional/quarters

from sentisense import SentiSenseClient

client = SentiSenseClient(api_key="ss_live_YOUR_KEY")
quarters = client.get_institutional_quarters()

Response Schema:

Field	Type	Description
value	string	Quarter identifier (e.g., "2024Q4")
label	string	Display label (e.g., "Q4 2024")
reportDate	string	Quarter end date (e.g., "2025-12-31")

Example Response:

[
  {
    "value": "2025Q4",
    "label": "Q4 2025",
    "reportDate": "2025-12-31"
  },
  {
    "value": "2025Q3",
    "label": "Q3 2025",
    "reportDate": "2025-09-30"
  }
]

---

GET /flows

Returns aggregate institutional buying and selling activity per stock ticker for a given quarter, split into inflows (net buying) and outflows (net selling). Shows net position changes, new vs. closed positions, and breakdowns by filer category.

Authentication: PRO required. Free users receive a preview of the top 5 results per direction.

Parameters:

Parameter	Type	Required	Default	Description
reportDate	date (ISO)	Yes	-	Filing deadline date from /quarters (e.g., 2025-12-31)
limit	integer	No	50	Max results per direction (capped at 100)

Example Request:

curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/institutional/flows?reportDate=2025-12-31&limit=20"

client = SentiSenseClient(api_key="ss_live_YOUR_KEY")
flows = client.get_institutional_flows("2025-12-31", limit=20)
for flow in flows["data"]["inflows"]:
    print(f"{flow['ticker']}: net buy {flow['netSharesChange']:,} shares")

Response Schema:

The response is an object with two arrays: inflows (stocks with positive net institutional buying) and outflows (stocks with negative net institutional selling).

Field	Type	Description
inflows	array	Stocks with net positive institutional activity (see flow object below)
outflows	array	Stocks with net negative institutional activity (see flow object below)

Flow object fields:

Field	Type	Description
ticker	string	Stock ticker symbol
companyName	string	Company name
totalSharesBought	long	Total shares purchased across all filers
totalSharesSold	long	Total shares sold across all filers
netSharesChange	long	Net change (bought - sold)
newPositions	int	Number of filers opening new positions
increasedPositions	int	Number of filers increasing existing positions
decreasedPositions	int	Number of filers decreasing positions
soldOutPositions	int	Number of filers completely exiting
indexFundNetChange	long	Net share change from index funds
hedgeFundNetChange	long	Net share change from hedge funds
activistActivity	boolean	Whether any activist investors have activity
activistNetChange	long	Net share change from activist investors
pensionNetChange	long	Net share change from pension funds
bankNetChange	long	Net share change from banks
insuranceNetChange	long	Net share change from insurance companies
mutualFundNetChange	long	Net share change from mutual funds
sovereignWealthNetChange	long	Net share change from sovereign wealth funds
endowmentNetChange	long	Net share change from endowments
reportDate	string	Report date for this data

Example Response (PRO):

{
  "inflows": [
    {
      "ticker": "NVDA",
      "companyName": "NVIDIA Corporation",
      "totalSharesBought": 245000000,
      "totalSharesSold": 89000000,
      "netSharesChange": 156000000,
      "newPositions": 42,
      "increasedPositions": 318,
      "decreasedPositions": 156,
      "soldOutPositions": 28,
      "indexFundNetChange": 45000000,
      "hedgeFundNetChange": 78000000,
      "activistActivity": false,
      "activistNetChange": 0,
      "pensionNetChange": 12000000,
      "bankNetChange": 8000000,
      "insuranceNetChange": 3000000,
      "mutualFundNetChange": 5000000,
      "sovereignWealthNetChange": 2000000,
      "endowmentNetChange": 1000000,
      "reportDate": "2025-12-31"
    }
  ],
  "outflows": [
    {
      "ticker": "TSLA",
      "companyName": "Tesla, Inc.",
      "netSharesChange": -70000000,
      "..."
    }
  ]
}

Preview Response (Free/Unauthenticated):

{
  "isPreview": true,
  "previewReason": "PRO_REQUIRED",
  "data": {
    "inflows": [ "... top 5 results ..." ],
    "outflows": [ "... top 5 results ..." ]
  }
}

---

GET /holders/{ticker}

Returns the list of institutional holders for a specific stock, showing each institution's position size, value, and how it changed from the previous quarter. Only equity positions are included (bonds and options are excluded).

Authentication: PRO required. Free users receive a preview of the top 5 holders.

Parameters:

Parameter	Type	Required	Default	Description
ticker	path	Yes	-	Stock ticker symbol (e.g., AAPL)
reportDate	date (ISO)	Yes	-	Quarter end date (e.g., 2025-12-31)

Example Request:

curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/institutional/holders/AAPL?reportDate=2025-12-31"

client = SentiSenseClient(api_key="ss_live_YOUR_KEY")
holders = client.get_stock_holders("AAPL", "2025-12-31")

Response Schema:

Field	Type	Description
ticker	string	Stock ticker
companyName	string	Company name
reportDate	string	Report date
totalInstitutionalShares	long	Total shares held by all institutions
totalInstitutionalValue	long	Total value in USD
holderCount	int	Number of institutional holders
holders	array	List of individual holders (see below)

Holder object:

Field	Type	Description
filerCik	string	SEC CIK number
filerName	string	Institution name
filerCategory	string	Fund type: INDEX_FUND, HEDGE_FUND, ACTIVIST, PENSION, BANK, INSURANCE, MUTUAL_FUND, SOVEREIGN_WEALTH, ENDOWMENT, OTHER
shares	long	Current shares held
valueUsd	long	Position value in USD
changeType	string	"NEW", "INCREASED", "DECREASED", "SOLD_OUT", "UNCHANGED"
sharesChange	long	Change in shares from previous quarter
sharesChangePct	double	Percentage change

Example Response:

{
  "ticker": "AAPL",
  "companyName": "Apple Inc.",
  "reportDate": "2025-12-31",
  "totalInstitutionalShares": 12500000000,
  "totalInstitutionalValue": 2875000000000,
  "holderCount": 4521,
  "holders": [
    {
      "filerCik": "0001067983",
      "filerName": "Berkshire Hathaway Inc",
      "filerCategory": "HEDGE_FUND",
      "shares": 300000000,
      "valueUsd": 69000000000,
      "changeType": "DECREASED",
      "sharesChange": -100000000,
      "sharesChangePct": -25.0
    }
  ]
}

---

GET /activist

Returns activist investor positions where the change type is NEW or INCREASED — indicating activists taking new stakes or increasing existing ones. Useful for monitoring potential activist campaigns.

Authentication: PRO required. Free users receive a preview of the top 3 positions.

Parameters:

Parameter	Type	Required	Default	Description
reportDate	date (ISO)	Yes	-	Quarter end date (e.g., 2025-12-31)

Example Request:

curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/institutional/activist?reportDate=2025-12-31"

client = SentiSenseClient(api_key="ss_live_YOUR_KEY")
activists = client.get_activist_positions("2025-12-31")

Response Schema:

Field	Type	Description
filerCik	string	SEC CIK number
filerName	string	Activist investor name
ticker	string	Target company ticker
companyName	string	Target company name
shares	long	Current shares held
valueUsd	long	Position value in USD
changeType	string	"NEW" or "INCREASED"
sharesChange	long	Change in shares
sharesChangePct	double	Percentage change (0 for new positions)
filedDate	string	Date the 13F was filed
reportDate	string	Reporting quarter date

Example Response:

[
  {
    "filerCik": "0001336528",
    "filerName": "Pershing Square Capital Management",
    "ticker": "HLT",
    "companyName": "Hilton Worldwide Holdings Inc",
    "shares": 10250000,
    "valueUsd": 2460000000,
    "changeType": "INCREASED",
    "sharesChange": 1500000,
    "sharesChangePct": 17.1,
    "filedDate": "2025-12-31",
    "reportDate": "2024-12-31"
  }
]

---

GET /bonds

Returns convertible bond flows grouped by base ticker. Convertible bonds are detected from SEC 13F filings where the ticker contains bond notation (e.g., "ABNB 0 03/15/26"). Useful for identifying hedge fund arbitrage strategies.

Authentication: PRO required. Free users receive a preview of the top 3 results.

Parameters:

Parameter	Type	Required	Default	Description
reportDate	date (ISO)	Yes	-	Quarter end date (e.g., 2025-12-31)

Example Request:

curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/institutional/bonds?reportDate=2025-12-31"

Response Schema:

Field	Type	Description
baseTicker	string	Base equity ticker (e.g., "ABNB")
companyName	string	Company name
positionCount	int	Number of institutional positions in this bond
totalValue	long	Total position value in USD
netSharesChange	long	Net change in shares/units
bondTickers	string	Comma-separated bond notations (e.g., "ABNB 0 03/15/26, ABNB 0.5 06/15/27")
hedgeFundCount	int	Number of hedge funds holding this bond

Example Response:

[
  {
    "baseTicker": "ABNB",
    "companyName": "Airbnb Inc",
    "positionCount": 24,
    "totalValue": 850000000,
    "netSharesChange": 5200000,
    "bondTickers": "ABNB 0 03/15/26",
    "hedgeFundCount": 18
  }
]

---

GET /options

Returns institutional options activity with call vs put breakdown per ticker. High call-to-put ratios indicate bullish institutional positioning; high put-to-call ratios indicate bearish positioning.

Authentication: PRO required. Free users receive a preview of the top 3 results.

Parameters:

Parameter	Type	Required	Default	Description
reportDate	date (ISO)	Yes	-	Quarter end date (e.g., 2025-12-31)

Example Request:

curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/institutional/options?reportDate=2025-12-31"

Response Schema:

Field	Type	Description
ticker	string	Stock ticker symbol
companyName	string	Company name
callValue	long	Total value of call option positions in USD
putValue	long	Total value of put option positions in USD
callPositions	int	Number of call option positions
putPositions	int	Number of put option positions
callNetChange	long	Net change in call option shares
putNetChange	long	Net change in put option shares
hedgeFundCount	int	Number of hedge funds with options in this ticker

Example Response:

[
  {
    "ticker": "TSLA",
    "companyName": "Tesla, Inc.",
    "callValue": 2400000000,
    "putValue": 1800000000,
    "callPositions": 156,
    "putPositions": 98,
    "callNetChange": 12000000,
    "putNetChange": 8000000,
    "hedgeFundCount": 45
  }
]