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-tier callers 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")
pending	boolean	true if the SEC's 45-day 13F filing window has not yet closed for this quarter — filings may still be arriving and data is incomplete. Check this before drawing conclusions from the most recent quarter.

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: All tiers return the unified wrapper {isPreview, previewReason, data}. The data field 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
avgClosePrice	float | null	Quarterly average closing price for the ticker. null when not yet cached.
dollarFlowUsd	float	Dollar-weighted net flow: netSharesChange × avgClosePrice. 0 when avgClosePrice is null; clients should fall back to displaying netSharesChange. Inflows are sorted by dollarFlowUsd descending, outflows ascending.

Example Response:

{
  "isPreview": false,
  "previewReason": null,
  "data": {
    "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,
        "..."
      }
    ]
  }
}

FREE tier: same shape with isPreview: true and data truncated.

---

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: All tiers return the unified wrapper {isPreview, previewReason, data}. The data field contains the holder object described below.

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:

{
  "isPreview": false,
  "previewReason": null,
  "data": {
    "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
      }
    ]
  }
}

FREE tier: same shape with isPreview: true and data truncated.

---

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: All tiers return the unified wrapper {isPreview, previewReason, data}. The data field is an array of activist position objects described below.

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:

{
  "isPreview": false,
  "previewReason": null,
  "data": [
    {
      "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"
    }
  ]
}

FREE tier: same shape with isPreview: true and data truncated.

---

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: All tiers return the unified wrapper {isPreview, previewReason, data}. The data field is an array of bond flow objects described below.

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:

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

FREE tier: same shape with isPreview: true and data truncated.

---

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: All tiers return the unified wrapper {isPreview, previewReason, data}. The data field is an array of options activity objects described below.

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:

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

FREE tier: same shape with isPreview: true and data truncated.

---

GET /institutions

Discover the universe of institutions: a paginated, AUM-ranked list of filers with their slug and metadata, so you can find what is worth querying without knowing slugs upfront. Each institution is rolled up by parent filer, so a multi-filer manager (e.g. Vanguard, which files under a parent plus multiple subsidiary CIKs) appears exactly once with its combined AUM. This endpoint is summary only; use GET /institution/{slugOrCik} for a filer's full holdings.

Authentication: API key required. This is a discovery endpoint: it does not consume your monthly quota (per-minute rate limits still apply), and every API key holder receives the full list.

Parameters: (all optional)

Parameter	Type	Required	Default	Description
category	string	No	-	Filter by filer category: INDEX_FUND, HEDGE_FUND, ACTIVIST, PENSION, BANK, INSURANCE, MUTUAL_FUND, SOVEREIGN_WEALTH, ENDOWMENT, OTHER
minAumUsd	long	No	-	Minimum total AUM in USD (e.g. 10000000000 for $10B and up)
limit	integer	No	50	Page size (capped at 200)
offset	integer	No	0	Pagination offset
sort	string	No	aumDesc	aumDesc, aumAsc, or nameAsc. Ordering is deterministic (stable tie-break), so pagination is consistent across requests.
quarter	string	No	latest	AUM snapshot quarter as YYYYQN (e.g. 2026Q1). Defaults to the latest available quarter.

Bad inputs (unknown category, unknown sort, negative offset/minAumUsd, or a quarter with no data) return 400 with {error, message}.

Example Request:

curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/institutional/institutions?category=HEDGE_FUND&minAumUsd=10000000000&limit=20"

client = SentiSenseClient(api_key="ss_live_YOUR_KEY")
page = client.list_institutions(category="HEDGE_FUND", min_aum_usd=10_000_000_000, limit=20)
for inst in page["institutions"]:
    print(inst["urlSlug"], inst["totalValueUsd"])

Response Schema: Returns the unified wrapper {isPreview, previewReason, data}. For this endpoint isPreview is always false and previewReason is always null. The data object is described below.

Field	Type	Description
data.quarter	string	Quarter of the AUM snapshot (e.g. "2026Q1")
data.totalCount	int	Total institutions matching the filters, before pagination
data.offset	int	Offset applied to this page
data.limit	int	Page size applied to this page
data.institutions	array	The page of institution summaries (see below)

Institution object:

Field	Type	Description
cik	string	SEC Central Index Key of the institution
urlSlug	string	URL slug for routing to GET /institution/{slugOrCik}
displayName	string	Cleaned display name
filerCategory	string	Filer category (may be null if unclassified)
totalValueUsd	long	Total AUM in USD for the quarter (rolled-up across the filer group)
holdingsCount	int	Distinct equity tickers held this quarter (rolled-up, de-duped)
multiCikRollup	boolean	true when this institution aggregates multiple related filer CIKs
childCikCount	int	Number of subsidiary filers rolled up under this institution (0 when not a rollup)

Example Response:

{
  "isPreview": false,
  "previewReason": null,
  "data": {
    "quarter": "2026Q1",
    "totalCount": 7842,
    "offset": 0,
    "limit": 50,
    "institutions": [
      {
        "cik": "0001067983",
        "urlSlug": "Berkshire-Hathaway",
        "displayName": "Berkshire Hathaway",
        "filerCategory": "HEDGE_FUND",
        "totalValueUsd": 314000000000,
        "holdingsCount": 38,
        "multiCikRollup": false,
        "childCikCount": 0
      }
    ]
  }
}

---

GET /institution/{slugOrCik}

Returns the full profile, summary stats, and current-quarter equity holdings for a specific institutional filer. Resolved either by URL slug (e.g. Berkshire-Hathaway) or by SEC CIK (e.g. 1067983).

Authentication: PRO required. Free users receive the profile and summary stats in full plus the top 10 holdings; PRO users get the full holdings array.

Parameters:

Parameter	Type	Required	Default	Description
slugOrCik	path	Yes	-	URL slug (e.g. Berkshire-Hathaway) or numeric CIK

Example Request:

curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/institutional/institution/Berkshire-Hathaway"

Response Schema:

Field	Type	Description
isPreview	boolean	true when the caller is on the FREE tier
previewReason	string	"PRO_REQUIRED" or null
data.filerCik	string	SEC Central Index Key
data.displayName	string	Cleaned filer display name
data.urlSlug	string	URL slug for routing
data.filerCategory	string	Filer category (e.g. INDEX_FUND, HEDGE_FUND, ACTIVIST, BANK, INSURANCE, MUTUAL_FUND, PENSION, SOVEREIGN_WEALTH, ENDOWMENT)
data.totalValueUsd	long	Total AUM in USD (sum of equity position values for the latest quarter)
data.holdingsCount	int	Total number of equity holdings (full count, even when holdings is truncated)
data.latestReportDate	string	Report date of the latest quarter (ISO date)
data.quartersTracked	int	Number of quarters with data
data.newPositions	int	Count of NEW positions in the latest quarter
data.increasedPositions	int	Count of INCREASED positions
data.decreasedPositions	int	Count of DECREASED positions
data.soldOutPositions	int	Count of SOLD_OUT positions
data.holdings	array	Holdings array sorted by value descending (PRO: full list; FREE: top 10)

Holding object:

Field	Type	Description
ticker	string	Stock ticker
companyName	string	Company name
shares	long	Shares held
valueUsd	long	Position value in USD
changeType	string	NEW, INCREASED, DECREASED, SOLD_OUT, or UNCHANGED
sharesChange	long	Share count change vs previous quarter
sharesChangePct	double	Percent change vs previous quarter
portfolioWeight	double	Position weight in the institution's total portfolio (%)

Returns 404 if the slug or CIK does not match a known filer.