SentiSense Python SDK
Official Python SDK for the SentiSense market intelligence API.
Installation
pip install sentisense
Quick Start
from sentisense import SentiSenseClient
client = SentiSenseClient("your-api-key")
# Get a stock price
price = client.get_stock_price("AAPL")
print(price)
# Get multiple stock prices
prices = client.get_stock_prices(["AAPL", "MSFT", "GOOGL"])
# Check market status
status = client.get_market_status()
print(status)
# Get latest news for a stock
news = client.get_documents_by_ticker("TSLA", source="news", days=7)
# Search across news and social media
results = client.search_documents("AI earnings surprise")
# Get mention time series for a stock (v2 metrics API)
mentions = client.get_metrics("NVDA", metric_type="mentions")
# Get sentiment time series
sentiment = client.get_metrics("NVDA", metric_type="sentiment")
# Get mentions broken down by source
dist = client.get_metrics_distribution("NVDA", metric_type="mentions", dimension="source")
Authentication
All API requests require an API key. You can generate one from your Developer Console.
client = SentiSenseClient("your-api-key")
For full endpoint documentation, request/response schemas, and interactive examples, see the API Documentation.
API Reference
Stocks
| Method | Description |
|---|---|
get_stock_price(ticker) |
Real-time price for a single stock |
get_stock_prices(tickers) |
Real-time prices for multiple stocks |
get_stock_profile(ticker) |
Company profile |
get_stock_entities(ticker) |
Tracked entities related to a stock (executives, products) |
get_stock_ai_summary(ticker, depth="basic") |
Curated AI research report. depth="deep" returns the full report and consumes one report view |
get_stock_chart(ticker, timeframe="1M") |
OHLCV chart data, returned as a bare list of bars (oldest first) |
get_all_stocks() |
List of available tickers |
get_all_stocks_detailed() |
Tickers with company names and entity IDs |
get_market_status() |
Market open/closed status |
get_fundamentals(ticker, timeframe="quarterly") |
Financial fundamentals |
get_current_fundamentals(ticker) |
Most recent fundamentals snapshot |
get_historical_revenue(ticker) |
Historical revenue series |
get_short_interest(ticker) |
Short interest (FINRA bi-monthly) |
get_float(ticker) |
Shares float |
get_short_volume(ticker) |
Daily short-sale volume (FINRA) |
Knowledge Base
| Method | Description |
|---|---|
get_popular_kb_entities() |
Popular KB entities (search suggestions) |
News & Documents
| Method | Description |
|---|---|
get_documents_by_ticker(ticker, source?, days?, hours?, limit?) |
News and social posts for a stock |
get_documents_by_ticker_range(ticker, start_date, end_date) |
Documents within a date range |
get_documents_by_entity(entity_id) |
Documents for a KB entity |
search_documents(query, source?, days?, limit?) |
Natural language search across news and social |
get_documents_by_source(source, days?, hours?, limit?) |
Latest from a source ("news", "reddit", "x", "substack") |
get_stories(limit?, days?, expanded?) |
AI-curated news story clusters |
get_stories_by_ticker(ticker, limit?) |
Stories for a specific stock |
Metrics (v2)
| Method | Description |
|---|---|
get_metrics(symbol, metric_type="sentiment", start_time?, end_time?, max_data_points?) |
Time series for a metric (mentions, sentiment, sentisense_score, social_dominance, creators) |
get_metrics_distribution(symbol, metric_type="mentions", dimension="source", start_time?, end_time?) |
Metric distribution by dimension (e.g. mentions by source) |
Note:
start_timeandend_timeare epoch milliseconds.
Institutional Flows (13F)
| Method | Description |
|---|---|
get_institutional_quarters() |
Available 13F reporting quarters |
get_institutional_flows(report_date=None, limit=50) |
Fund flows for a quarter (omit report_date for the latest) |
get_stock_holders(ticker, report_date, limit=None, offset=None, sort_by=None, sort_dir=None) |
Institutional holders for a stock (see paging note below) |
get_activist_positions(report_date) |
Activist investor positions |
Paging the holder list
A widely held ticker returns thousands of rows: a megacap quarter is roughly 6,000
holders and 1.5 MB on the wire. Pass limit unless you really want the whole list.
Omitting every paging argument sends the original unbounded request, so existing code
keeps working.
| Argument | Values |
|---|---|
limit |
Maximum rows to return. Must be >= 1; values above 1000 are capped server-side. Omit for the full list. |
offset |
Row offset to start from, used with limit. Server default is 0. |
sort_by |
"shares" (server default), "valueUsd", or "sharesChangePct". |
sort_dir |
"desc" (server default) or "asc". |
import os
from sentisense import SentiSenseClient
client = SentiSenseClient(os.environ["SENTISENSE_API_KEY"])
# Top 10 holders by position value, largest first
top = client.get_stock_holders(
"AAPL", "2026-03-31", limit=10, sort_by="valueUsd", sort_dir="desc"
)
for holder in top.holders:
print(holder["filerName"], holder["valueUsd"])
# Walk the list a page at a time
page = client.get_stock_holders("AAPL", "2026-03-31", limit=100, offset=100)
print(f"{page.returnedCount} rows from offset {page.offset} of {page.holderCount}")
Paged responses carry returnedCount and offset next to the holder rows, so you can
walk the list without re-counting it yourself.
Analyst Ratings
The price target cone (mean, high, low, upside %) and consensus are free for everyone, full data via API: we give it away. Upgrade/downgrade feeds and forward EPS estimates are limited on free, unlimited on PRO.
| Method | Description |
|---|---|
get_analyst_consensus(ticker) |
Price target band (mean, high, low), analyst count, upside %. Free for everyone, full data. |
get_analyst_actions(ticker, lookback_days=90) |
Recent upgrade/downgrade actions. Free: 3 most recent. PRO: unlimited. |
get_analyst_estimates(ticker) |
Forward EPS estimates and earnings surprise history. Free: 1 quarter. PRO: full history. |
get_analyst_market_activity(lookback_days=30) |
Market-wide recent analyst actions across all tickers (PRO). |
Company KPIs (PRO)
| Method | Description |
|---|---|
get_company_kpis(ticker) |
Company-specific KPI time-series (product metrics, segment revenue). Free tier returns metadata only (empty kpis array); PRO returns full series. |
list_kpi_coverage() |
List all tickers with curated KPI coverage (free, no quota cost) |
ETFs (beta)
Composition data is public; the holdings-weighted aggregate views follow the same PRO-with-preview pattern as Analyst/Insider. Aggregates synthesize fund-level views from each constituent's per-stock data (analyst coverage, insider trades, sentiment), weighted by allocation. Every aggregate response carries a coverage block so you see exactly how much of the fund's AUM the underlying data covered.
| Method | Description |
|---|---|
list_etfs() |
Every ETF tracked by SentiSense. Returns ticker, fund name, issuer, tracked index, asset class. |
get_etf_holdings(ticker) |
Full composition: per-holding weights and freshness metadata. |
get_etf_analyst_aggregate(ticker) |
Holdings-weighted analyst consensus (weighted upside, distribution). Free: headline + coverage. PRO: + topContributors. |
get_etf_insider_aggregate(ticker, lookback_days=30) |
Holdings-weighted Form 4 net flow over a configurable window. Free: headline + buy/sell split. PRO: + topContributors. |
get_etf_sentiment_aggregate(ticker) |
Two SentiSense readings side-by-side: constituent-weighted and direct (mentions of the fund itself). |
Error Handling
The SDK raises typed exceptions for API errors:
from sentisense import SentiSenseClient, AuthenticationError, RateLimitError
client = SentiSenseClient("your-api-key")
try:
price = client.get_stock_price("AAPL")
except AuthenticationError:
print("Invalid or missing API key")
except RateLimitError:
print("Rate limit exceeded, try again later")
| Exception | HTTP Status | Description |
|---|---|---|
AuthenticationError |
401, 403 | Invalid or missing API key |
NotFoundError |
404 | Resource not found |
RateLimitError |
429 | Rate limit exceeded |
DeepHistoryUnavailable |
202 | Deep chart history (10Y, MAX) is still being assembled; retry shortly |
APIError |
Other 4xx/5xx | General API error |
All exceptions inherit from SentiSenseError and include .status_code, .message, and .response attributes.
Not yet in the Python SDK
A few endpoints available in the Node SDK are intentionally not yet exposed here
(low-traffic / discovery-convenience surfaces). Call them directly over HTTP if you
need them: /api/v1/stocks/images, /api/v1/stocks/descriptions,
/api/v1/stocks/popular, /api/v1/documents/stories/{clusterId} (single-story
detail), and the metrics breakdown endpoint.
License
MIT - see LICENSE for details.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file sentisense-0.36.0.tar.gz.
File metadata
- Download URL: sentisense-0.36.0.tar.gz
- Upload date:
- Size: 51.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.9.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
241d695b3dc1a932170d73438faa579498e3df288503429540a0340dcce6a2a7
|
|
| MD5 |
2229b2f992a4e3ca904e80f719522b9c
|
|
| BLAKE2b-256 |
7d71ae64497880b07253ee994069978dac0015c207341b7680ee4f8881f9f97c
|
File details
Details for the file sentisense-0.36.0-py3-none-any.whl.
File metadata
- Download URL: sentisense-0.36.0-py3-none-any.whl
- Upload date:
- Size: 35.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.9.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
65fb78260d0d64315893982872e0f6c690ce1e39b65f01e63925d4ea46ef00d5
|
|
| MD5 |
95fbdf9c651efc40a4acc42c7dd34921
|
|
| BLAKE2b-256 |
17d8a9b082a5c50df3071d8d2b7a06fac4395f3e60a0381be5260735326272e5
|
