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
• Build quantitative strategies based on institutional flow signals

Access: The /quarters endpoint is public. All other endpoints require a PRO subscription. Free users see a limited preview (top 2-3 results) with isPreview: true in the response.

---

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="ssk_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	Filing deadline date (e.g., "2025-02-14")

Example Response:

[
  {
    "value": "2024Q4",
    "label": "Q4 2024",
    "reportDate": "2025-02-14"
  },
  {
    "value": "2024Q3",
    "label": "Q3 2024",
    "reportDate": "2024-11-14"
  }
]

---

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 fund type.

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

Parameters:

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

Example Request:

curl -H "X-API-Key: ssk_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/institutional/flows?reportDate=2025-02-14&limit=20"

client = SentiSenseClient(api_key="ssk_YOUR_KEY")
flows = client.get_institutional_flows("2025-02-14", limit=20)
for flow in flows["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 specifically
hedgeFundNetChange	long	Net share change from hedge funds specifically
activistActivity	boolean	Whether any activist investors have activity
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,
      "reportDate": "2025-02-14"
    }
  ],
  "outflows": [
    {
      "ticker": "TSLA",
      "companyName": "Tesla, Inc.",
      "totalSharesBought": 50000000,
      "totalSharesSold": 120000000,
      "netSharesChange": -70000000,
      "newPositions": 15,
      "increasedPositions": 95,
      "decreasedPositions": 280,
      "soldOutPositions": 45,
      "indexFundNetChange": -20000000,
      "hedgeFundNetChange": -35000000,
      "activistActivity": false,
      "reportDate": "2025-02-14"
    }
  ]
}

Preview Response (Free/Unauthenticated):

{
  "isPreview": true,
  "previewReason": "PRO_REQUIRED",
  "data": {
    "inflows": [
      { "ticker": "NVDA", "companyName": "NVIDIA Corporation", "..." : "..." }
    ],
    "outflows": [
      { "ticker": "TSLA", "companyName": "Tesla, Inc.", "..." : "..." }
    ]
  }
}

---

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.

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

Parameters:

Parameter	Type	Required	Default	Description
ticker	path	Yes	-	Stock ticker symbol (e.g., AAPL)
reportDate	date (ISO)	Yes	-	Filing deadline date (e.g., 2025-02-14)

Example Request:

curl -H "X-API-Key: ssk_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/institutional/holders/AAPL?reportDate=2025-02-14"

client = SentiSenseClient(api_key="ssk_YOUR_KEY")
holders = client.get_stock_holders("AAPL", "2025-02-14")

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 (e.g., "HEDGE_FUND", "INDEX_FUND")
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-02-14",
  "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 2 positions.

Parameters:

Parameter	Type	Required	Default	Description
reportDate	date (ISO)	Yes	-	Filing deadline date (e.g., 2025-02-14)

Example Request:

curl -H "X-API-Key: ssk_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/institutional/activist?reportDate=2025-02-14"

client = SentiSenseClient(api_key="ssk_YOUR_KEY")
activists = client.get_activist_positions("2025-02-14")

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-02-14",
    "reportDate": "2024-12-31"
  }
]