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
• Follow how institutional ownership of a stock changed over the last three to five years
• 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 11 categories: INDEX_FUND, HEDGE_FUND, ACTIVIST, PENSION, BANK, INSURANCE, MUTUAL_FUND, SOVEREIGN_WEALTH, ENDOWMENT, CONGLOMERATE, 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

/activist, /bonds and /options require a reportDate parameter. /quarters, /flows and /holders/{ticker} do not: omit it for the latest quarter, or pass one for a specific quarter. Do not hardcode dates: available quarters change as new SEC filings are processed. Call GET /quarters first to get valid dates:

Skip pending quarters. The first entry in the list is the current quarter, and it carries pending: true through the effective SEC filing deadline day in New York (45 days after quarter end, rolled past weekends and federal holidays). Passing a pending reportDate to /activist, /bonds, or /holders/{ticker} is a valid call, but it returns few rows or an empty data array, because almost nothing has been filed yet. Take the first quarter with pending: false unless you specifically want early-filer coverage. (Omitting reportDate on /holders/{ticker} already applies this rule for you, per ticker.)

# Step 1: Get available quarters, then take the first fully filed one
quarters = client.get_institutional_quarters()
filed = [q for q in quarters if not q.get("pending")]
latest_date = filed[0]["reportDate"]  # e.g., "2026-03-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: API key required

Parameters: None

Example Request:

curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "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 through the effective SEC filing deadline day in New York, including the weekend and federal-holiday roll; filings may still be arriving.
ownershipEligible	boolean	true from the New York calendar day after the effective SEC filing deadline; it does not certify that every institution filed.
ownershipEligibleAt	string	New York calendar date (ISO) after the effective filing deadline when the quarter becomes eligible.

Example Response:

[
  {
    "value": "2026Q1",
    "label": "Q1 2026",
    "reportDate": "2026-03-31",
    "ownershipEligible": false,
    "ownershipEligibleAt": "2026-05-16",
    "pending": true
  },
  {
    "value": "2025Q4",
    "label": "Q4 2025",
    "reportDate": "2025-12-31",
    "ownershipEligible": true,
    "ownershipEligibleAt": "2026-02-18",
    "pending": false
  },
  {
    "value": "2025Q3",
    "label": "Q3 2025",
    "reportDate": "2025-09-30",
    "ownershipEligible": true,
    "ownershipEligibleAt": "2025-11-15",
    "pending": false
  }
]

The list is sorted newest-first, so quarters[0] is the one most likely to be pending. Filter on pending rather than indexing blind.

---

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)	No	latest	Quarter to fetch (e.g., 2025-12-31). Omit to get the latest available quarter, including a still-open one (labeled with isPending plus filer coverage). Pass one from /quarters for a specific quarter.
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 carrying the served-quarter metadata plus two arrays: inflows (stocks with positive net institutional buying) and outflows (stocks with negative net institutional selling).

Field	Type	Description
reportDate	string	The quarter actually served (useful when you omitted the param)
isPending	boolean	true through the effective SEC filing deadline day in New York, so only early filers are represented
filerCount	int | null	Filers represented when isPending is true (e.g. 578); null otherwise
baselineFilerCount	int | null	Total expected filers for a complete quarter (e.g. 8789), for coverage context; null when not pending
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
conglomerateNetChange	long	Net share change from diversified holding companies / conglomerates
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,
        "conglomerateNetChange": 0,
        "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). Institutions that file through multiple SEC CIKs (for example Vanguard's family of registered advisers) are rolled up into a single holder row under the parent institution; the cikCount field reports how many filers were merged.

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)	No	latest	Quarter end date (e.g., 2025-12-31). Omit it and the endpoint resolves the most recent quarter in which this ticker actually has holders, preferring a settled quarter over a still-filing one, and echoes the quarter it used in data.reportDate. Pass one from /quarters for a specific quarter.
limit	int	No	-	Page size (1 to 1000). When present, the response is a sorted page and includes paging metadata (returnedCount, offset) plus a notableChanges summary. When omitted, the full holder list is returned (legacy behavior, unchanged).
offset	int	No	0	Start position within the sorted holder list. Only used with limit.
sortBy	string	No	shares	Sort field: shares, valueUsd, sharesChange or sharesChangePct. Only used with limit. sharesChange ranks by the absolute share change, so sortDir=desc lists the quarter's largest buyers and asc its largest sellers.
sortDir	string	No	desc	Sort direction: asc or desc. Only used with limit.

Paging applies to PRO (full) responses. Free-tier preview responses ignore the paging parameters. A mega-cap can have 5,000+ institutional holders, so paged requests are strongly recommended for interactive clients.

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"

# Or let the endpoint pick the latest quarter that has holders for this ticker
curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/institutional/holders/AAPL?limit=25"

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

Share classes and renamed tickers. Holders are per share class, because 13F filings report each class under its own CUSIP: GOOG returns Alphabet's Class C roster and GOOGL its Class A roster, BRK.A returns Berkshire's Class A roster only, and Z Zillow's Class C roster. Spelling variants resolve to the same security (BRKB for BRK.B), and a recognized former ticker resolves to the current one, including quarters whose filings are still recorded under the old symbol. Before this change (2026-10-16), GOOG, BRK.A and Z returned the other class's holders.

Response Schema: All tiers return the unified wrapper {isPreview, previewReason, data}. Successful holders responses add four fields saying which security was answered:

Field	Type	Description
requestedTicker	string	The ticker as you passed it, uppercased
resolvedTicker	string	The security the roster is for (GOOG, BRK.A, or the current ticker of a renamed company)
resolution	string	exact, spelling (a separator variant), share_class (a separately listed class) or rename (a former ticker)
storedTicker	string	The raw 13F key: the symbol this quarter's filings are recorded under (for example BRKA or BRKB, or a renamed company's old ticker). Use data.ticker or resolvedTicker for display and joins.

The data field contains the holder object described below.

Field	Type	Description
ticker	string	The canonical ticker of the security answered for, in SentiSense's spelling: the same value as resolvedTicker (BRK.A for a BRK.A, BRK-A or BRKA request, BRK.B for BRKB, a renamed company's current ticker). The raw 13F key, which can differ (BRKA, BRKB, a former ticker), is in the response's storedTicker. Earlier responses returned that raw key here.
companyName	string	Company name
reportDate	string	The quarter actually served (useful when you omitted the param)
selection	object	Quarter choice: mode (DEFAULT or EXPLICIT), status (settled or filing), policyVersion (v2-sec-deadline-next-day), marketDefaultReportDate and isStaleForMarket. The market date is the newest eligible quarter; the stale flag indicates that this ticker is served from an older quarter. An explicit reportDate remains the quarter requested.
earlyFilersStatus	string	AVAILABLE when earlyFilers is present, NONE when no newer filing quarter is observed, or UNAVAILABLE when the supplementary filing read fails. The selected-quarter holder roster remains available when this status is UNAVAILABLE.
earlyFilers	object	Newer, still-filing quarter observed for this ticker; omitted on NONE or UNAVAILABLE. Contains reportDate, status (filing), holderCount (positive-share holder families for this ticker), distinctFilerCount (market-wide distinct reporting filers), baselineFilerCount (market-wide filers in the selected settled quarter) and optional coveragePct. Coverage is the selected-quarter reported value of individual filers confirmed to have filed for the newer quarter, including filers that exited this ticker, divided by total selected-quarter institutional value for this ticker, as a percentage; omitted when filing presence or baseline value is unavailable, or the raw baseline sum does not reconcile with the served total. The positive-position family count and the reporting-filer coverage cohort are distinct: coverage includes confirmed exits.
totalInstitutionalShares	long	Total shares held by all institutions
totalInstitutionalValue	long	Total value in USD
sharesOutstanding	long	The share class's shares outstanding as last filed on sharesOutstandingAsOf (the latest cover-page count, not a quarter-end count). Omitted for ADRs and other unsupported security types, or when no dated per-class count exists.
sharesOutstandingAsOf	string	Date the sharesOutstanding count was read: the day the quarter settles, or today while it is still filing. Omitted with sharesOutstanding.
institutionalOwnershipPct	double	totalInstitutionalShares as a percent of sharesOutstanding. Can pass 100% because lent shares are reported by both lender and buyer. Omitted with sharesOutstanding, and when the ratio is implausible (above 150%), which signals a unit mismatch rather than real ownership.
holderCount	int	Number of institutional holders for the quarter (always the full count, even on paged responses)
holders	array	List of individual holders (see below)
notableHolders	array	Matched, positive-share institutions from the selected quarter's full roster. Free returns up to five names and identifiers only; PRO also returns position and change fields. This list does not expand the holders preview. The list and notableHoldersScope are omitted if the full-roster lookup is unavailable; a verified search with no matches returns an empty array.
notableHoldersScope	string	full_roster when notable matches were checked against the selected quarter's full roster.
comparisonReportDate	string	Immediately preceding calendar quarter targeted for share-change comparisons. It can be present when comparisonStatus says the data is unavailable or incomplete; omitted when no supported prior comparison date exists.
comparisonStatus	string	Conservative summary across the response: AVAILABLE, PRIOR_QUARTER_UNAVAILABLE, INCOMPLETE_INPUT, INCOMPLETE_FAMILY_COVERAGE or UNAVAILABLE. Individual holders can have valid changes even when this summary is incomplete; check each holder's comparisonStatus.
returnedCount	int	Paged responses only: number of holders in this page
offset	int	Paged responses only: start position of this page in the sorted list
notableChanges	object	Paged responses only: {count, top} where count is the number of holders with a 10%+ position change on 10k+ shares, and top is the 5 largest such changes by dollar impact (holder objects)

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, CONGLOMERATE, 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
entitySlug	string	URL slug for the institution's detail page, or null if unmapped
cikCount	int	Number of sister filer CIKs merged into this row; null for ordinary single-filer rows
pctOfClassOutstanding	double	This holder's shares as a percent of the response's sharesOutstanding; omitted when that denominator is omitted. Never estimated.
comparisonStatus	string	AVAILABLE, PRIOR_QUARTER_UNAVAILABLE, INCOMPLETE_INPUT, INCOMPLETE_FAMILY_COVERAGE or UNAVAILABLE. Legacy change fields can remain present under other statuses; only AVAILABLE supports this holder's quarter-change claim.

Notable-holder object: filerCik, filerName and entitySlug identify the institution. PRO responses can also carry shares, valueUsd, comparisonStatus, sharesChange, sharesChangePct and changeType; only AVAILABLE supports a quarter-change claim. Free omits position and change values. A notable position marked NEW omits sharesChangePct because it has no prior-position percentage baseline.

Example Response:

{
  "isPreview": false,
  "previewReason": null,
  "data": {
    "ticker": "AAPL",
    "companyName": "APPLE INC",
    "reportDate": "2025-12-31",
    "selection": {
      "mode": "EXPLICIT",
      "status": "settled",
      "policyVersion": "v2-sec-deadline-next-day",
      "marketDefaultReportDate": "2026-06-30",
      "isStaleForMarket": true
    },
    "earlyFilersStatus": "AVAILABLE",
    "earlyFilers": {
      "reportDate": "2026-09-30",
      "status": "filing",
      "holderCount": 1959,
      "distinctFilerCount": 2268,
      "baselineFilerCount": 8848,
      "coveragePct": 3.04
    },
    "totalInstitutionalShares": 9493579808,
    "totalInstitutionalValue": 2588272356084,
    "holderCount": 6079,
    "comparisonReportDate": "2025-09-30",
    "comparisonStatus": "INCOMPLETE_FAMILY_COVERAGE",
    "holders": [
      {
        "filerCik": "0000102909",
        "filerName": "Vanguard",
        "filerCategory": "INDEX_FUND",
        "shares": 1428658707,
        "valueUsd": 388395156104,
        "changeType": "INCREASED",
        "sharesChange": 26929820,
        "sharesChangePct": 1.92,
        "comparisonStatus": "AVAILABLE",
        "entitySlug": "Vanguard",
        "cikCount": 3
      }
    ],
    "notableHoldersScope": "full_roster",
    "notableHolders": [
      {
        "filerCik": "0001067983",
        "filerName": "Berkshire Hathaway",
        "entitySlug": "Berkshire-Hathaway",
        "shares": 227917808,
        "valueUsd": 61961735283,
        "changeType": "DECREASED",
        "sharesChange": -10294956,
        "sharesChangePct": -4.32,
        "comparisonStatus": "AVAILABLE"
      }
    ]
  }
}

A PRO response captured 2026-10-23, trimmed to one holder and one notable holder. Because this call names an older quarter, selection.isStaleForMarket is true, and earlyFilers still reports the newest quarter that is filing. The summary comparisonStatus reads incomplete while this holder's own status is AVAILABLE, so its change figures are valid.

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

---

GET /holders/{ticker}/history

Returns a stock's institutional ownership one quarter per row, newest first: the number of holders, the share of the class they held, and the quarter's net shares bought or sold, dollar flow and position counts. Holder counts and totals roll multi-filer institutions up into one holder the same way /holders/{ticker} does, so a settled quarter here matches that quarter's holders response. The flow fields count every filer's position change in this ticker, including full exits: a filer that has filed for the quarter and no longer lists the stock is an exit, and its previous position counts as shares sold. A filer that has not filed yet is not counted until it does.

Authentication: API key required. PRO returns the full window; free keys receive the newest four quarters as a preview.

Latency: a ticker's history is computed from the filings the first time it is asked for and stored afterwards, so the first call for a rarely requested ticker can take several seconds. When too many of those computations are running at once, the call answers 503 with {"error": "history_busy"} and a Retry-After header in seconds; retry after that delay.

Parameters:

Parameter	Type	Required	Default	Description
ticker	path	Yes	-	Stock ticker symbol (e.g., AAPL). Share classes are answered separately, as on /holders/{ticker}.
quarters	int	No	12	How many of the newest 13F quarters to cover, from 1 to 20. Values above 20 are capped at 20; values below 1 return 400 invalid_quarters.

Example Request:

curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/institutional/holders/AAPL/history?quarters=8"

Response Schema: All tiers return the unified wrapper {isPreview, previewReason, data}. Free responses also carry totalCount, the number of quarters in the full window. data is an object with ticker (the security answered for, in SentiSense's spelling, such as BRK.B) and quarters, a list of quarter rows, newest first. A quarter in which the security had no 13F holdings is left out, so a ticker without coverage returns an empty list. The exception is a settled quarter in which every remaining holder left: it is returned with zero holders and those exits.

Quarter object:

Field	Type	Description
reportDate	string	Quarter end date (ISO)
value	string	Quarter identifier in YYYYQN form (e.g., 2026Q2)
label	string	Display label (e.g., Q2 2026)
status	string	settled once the quarter's filing deadline has passed, filing before; a filing quarter counts only the institutions that have filed so far
pending	boolean	true while status is filing, by the same rule as /quarters
holderCount	int	Institutional holders, with multi-filer institutions counted once
totalInstitutionalShares	long	Shares held by all reporting institutions
totalInstitutionalValue	long	Reported value of those shares in USD
sharesOutstanding	long	The share class's shares outstanding as last filed on the day the quarter settles, or today while it is still filing; omitted for ADRs and other unsupported security types, when no dated per-class count exists, or when institutions report more than 150% of it
institutionalOwnershipPct	double	totalInstitutionalShares as a percent of sharesOutstanding, which can pass 100% because lent shares are reported by both lender and buyer; omitted with sharesOutstanding
netSharesChange	long	totalSharesBought minus totalSharesSold
totalSharesBought	long	Sum of share increases across filers that opened or added to a position
totalSharesSold	long	Sum of share decreases across filers that trimmed or exited a position, as a positive number; an exit counts the filer's whole previous position
newPositions	int	Filer positions opened in the quarter
increasedPositions	int	Filer positions added to
decreasedPositions	int	Filer positions trimmed
soldOutPositions	int	Filer positions exited in the quarter: reported at zero shares, or left out of a filing for the quarter; a filer that has not filed yet is not counted
avgClosePrice	double	The quarter's average closing price in USD; omitted when the quarter is unpriced
dollarFlowUsd	double	netSharesChange multiplied by avgClosePrice, in USD; omitted when avgClosePrice is omitted

Example Response:

{
  "isPreview": false,
  "previewReason": null,
  "data": {
    "ticker": "AAPL",
    "quarters": [
      {
        "reportDate": "2026-09-30",
        "value": "2026Q3",
        "label": "Q3 2026",
        "status": "filing",
        "pending": true,
        "holderCount": 1500,
        "totalInstitutionalShares": 2500000000,
        "totalInstitutionalValue": 600000000000,
        "sharesOutstanding": 14600000000,
        "institutionalOwnershipPct": 17.12,
        "netSharesChange": -12000000,
        "totalSharesBought": 40000000,
        "totalSharesSold": 52000000,
        "newPositions": 120,
        "increasedPositions": 600,
        "decreasedPositions": 700,
        "soldOutPositions": 40,
        "avgClosePrice": 240.5,
        "dollarFlowUsd": -2886000000.0
      },
      {
        "reportDate": "2026-06-30",
        "value": "2026Q2",
        "label": "Q2 2026",
        "status": "settled",
        "pending": false,
        "holderCount": 6000,
        "totalInstitutionalShares": 9400000000,
        "totalInstitutionalValue": 2200000000000,
        "sharesOutstanding": 14600000000,
        "institutionalOwnershipPct": 64.38,
        "netSharesChange": 35000000,
        "totalSharesBought": 180000000,
        "totalSharesSold": 145000000,
        "newPositions": 300,
        "increasedPositions": 2400,
        "decreasedPositions": 2600,
        "soldOutPositions": 190,
        "avgClosePrice": 215.25,
        "dollarFlowUsd": 7533750000.0
      }
    ]
  }
}

Illustrative values, trimmed to two quarters. The newest row is still filing, so its holder count and ownership share cover only the institutions that have filed so far.

FREE tier: same shape with isPreview: true, the newest four quarters in data.quarters, and totalCount set to the number of quarters in the full window.

---

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). Use a quarter with pending: false from /quarters; a pending quarter returns an empty data array because the filings have not arrived yet.

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, CONGLOMERATE, OTHER
minAumUsd	long	No	-	Minimum total AUM in USD (e.g. 10000000000 for $10B and up)
q	string	No	-	Name search: case-insensitive match on institution display name or URL slug (max 100 chars). Combines with the other filters.
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, a q over 100 characters, 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. Resolution checks the URL slug first, then the exact CIK, then the CIK zero-padded to 10 digits; CIK inputs accept 1 to 10 digits with optional leading zeros (e.g. 1067983 or 0001067983).

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 SEC CIK of 1 to 10 digits with optional leading zeros (e.g. 1067983 or 0001067983)

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
upgrade	object	Present only when isPreview is true. Carries plan, message, price, url and relay: surface message and url to your user in one line, then continue with the preview data
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, CONGLOMERATE)
data.totalValueUsd	long	Total AUM in USD (sum of equity position values for the latest quarter)
data.holdingsCount	int	Number of holdings rows, including SOLD_OUT rows (shares 0); positions held is holdingsCount minus soldOutPositions. Full count, even when holdings is truncated
data.positionsHeld	int	Number of equity positions held in the latest quarter, computed as max(0, holdingsCount - soldOutPositions) for the full portfolio even when holdings is paged or 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.comparisonStatus	string	AVAILABLE when the position counts and each holding's change fields compare with the immediately preceding quarter, restated for stock splits and ticker renames. PRIOR_QUARTER_UNAVAILABLE, INCOMPLETE_FAMILY_COVERAGE, INCOMPLETE_INPUT or UNAVAILABLE mean they are not a quarter-over-quarter comparison.
data.comparisonReportDate	string	The preceding quarter used for changes; omitted when none applies.
data.successor	object	When this filer stopped filing because another filer now reports its 13F book (it filed a 13F-NT naming the new filer): filerCik, displayName and urlSlug of that filer. Omitted otherwise.
data.predecessors	array	The filers whose books this filer took over, each with filerCik, displayName and urlSlug. Omitted when there are none.
data.multiCikRollup	boolean	true when this institution aggregates 13F filings across multiple related filer CIKs (e.g. a parent plus subsidiaries)
data.childCikCount	int	Number of subsidiary filers rolled up under this institution (0 when not a rollup)
data.childCiks	array	The subsidiary CIKs rolled up under this institution (null when not a rollup)
data.holdings	array	Holdings array sorted by value descending (PRO: full list; FREE: top 10)
data.optionPositions	array	Long put/call legs disclosed on the same 13F, sorted by notional descending. PRO only, and omitted entirely when the filer disclosed no option legs

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 (%)

Option position object:

A 13F discloses long option legs alongside equity positions. Each leg carries the underlying's ticker, the underlying share count the contracts represent, and the notional value of that exposure. Some filers express a view on an underlying only through options, so a ticker can appear in optionPositions without appearing in holdings.

Option legs are kept in their own array rather than merged into holdings, and their notional is excluded from totalValueUsd and from every portfolioWeight. A 13F notional is not a stake and not premium paid, so summing the two would misstate the portfolio.

Field	Type	Description
ticker	string	Underlying ticker
companyName	string	Issuer name as disclosed on the filing
putCall	string	PUT or CALL
valueUsd	long	Notional exposure in USD as disclosed. Not premium paid, not a directional P&L
shares	long	Underlying shares represented by the contracts
changeType	string	NEW, INCREASED, DECREASED, or UNCHANGED vs the prior quarter's same leg

One row per (ticker, put/call): a filer holding both a put and a call on the same underlying gets two entries.

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