sentisense 0.77.0 → 0.78.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +230 -605
- package/dist/cli.cjs +146 -44
- package/dist/index.cjs +56 -31
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.mts +220 -10
- package/dist/index.d.ts +220 -10
- package/dist/index.mjs +56 -31
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -3,15 +3,9 @@
|
|
|
3
3
|
[](https://www.npmjs.com/package/sentisense)
|
|
4
4
|
[](https://opensource.org/licenses/MIT)
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
The official JavaScript and TypeScript client for the [SentiSense](https://sentisense.ai) API, plus a command line tool in the same package. It covers prices and fundamentals, news and social sentiment, the SentiSense Score and Rating, insider and congressional trades, 13F holdings, analyst ratings, earnings, options positioning, ETFs and a screener that mixes all of them.
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
- Works in Node.js 18+, Deno, Bun, and browsers
|
|
10
|
-
- Zero runtime dependencies (native `fetch`)
|
|
11
|
-
- Namespaced resources (`stocks`, `documents`, `institutional`, ...) and a typed error hierarchy
|
|
12
|
-
- A complete command line interface in the same package, runnable via `npx` with nothing to install
|
|
13
|
-
|
|
14
|
-
Get a free API key at [app.sentisense.ai/get-api-key](https://app.sentisense.ai/get-api-key). Full API docs at [sentisense.ai/docs/api](https://sentisense.ai/docs/api).
|
|
8
|
+
It ships its own types and has no runtime dependencies. It runs on Node 18+, Deno, Bun and the browser.
|
|
15
9
|
|
|
16
10
|
## Contents
|
|
17
11
|
|
|
@@ -29,6 +23,8 @@ Get a free API key at [app.sentisense.ai/get-api-key](https://app.sentisense.ai/
|
|
|
29
23
|
npm install sentisense
|
|
30
24
|
```
|
|
31
25
|
|
|
26
|
+
You need an API key. The free one at [app.sentisense.ai/get-api-key](https://app.sentisense.ai/get-api-key) works with every endpoint, or run `npx sentisense init` for a temporary key without signing up.
|
|
27
|
+
|
|
32
28
|
## Quick start
|
|
33
29
|
|
|
34
30
|
```typescript
|
|
@@ -36,105 +32,63 @@ import SentiSense from "sentisense";
|
|
|
36
32
|
|
|
37
33
|
const client = new SentiSense(); // reads SENTISENSE_API_KEY, or pass { apiKey }
|
|
38
34
|
|
|
39
|
-
const
|
|
40
|
-
console.log(
|
|
35
|
+
const tickers = await client.stocks.list();
|
|
36
|
+
console.log(tickers.length, "stocks covered");
|
|
41
37
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
const flows = await client.institutional.getFlows();
|
|
45
|
-
```
|
|
38
|
+
const price = await client.stocks.getPrice("NVDA");
|
|
39
|
+
console.log(price.currentPrice, price.changePercent);
|
|
46
40
|
|
|
47
|
-
|
|
41
|
+
const score = await client.entityMetrics.getMetrics("NVDA", { metricType: "sentisense_score" });
|
|
42
|
+
console.log("SentiSense Score:", score.at(-1)?.value);
|
|
48
43
|
|
|
49
|
-
|
|
44
|
+
for (const story of await client.documents.getStoriesByTicker("NVDA", { limit: 3 })) {
|
|
45
|
+
console.log(story.cluster.title);
|
|
46
|
+
}
|
|
50
47
|
|
|
51
|
-
|
|
52
|
-
|
|
48
|
+
const trades = await client.insider.getTrades("NVDA");
|
|
49
|
+
for (const trade of trades.data.slice(0, 5)) {
|
|
50
|
+
console.log(trade.insiderName, trade.transactionCode, trade.sharesTransacted);
|
|
51
|
+
}
|
|
53
52
|
```
|
|
54
53
|
|
|
55
|
-
|
|
54
|
+
## The CLI
|
|
56
55
|
|
|
57
|
-
|
|
58
|
-
export SENTISENSE_API_KEY=<your key>
|
|
59
|
-
# or store it once, owner-readable only, at ~/.config/sentisense/config.json
|
|
60
|
-
npx -y sentisense@latest auth <your key>
|
|
56
|
+
Try the API without writing code:
|
|
61
57
|
|
|
62
|
-
|
|
58
|
+
```bash
|
|
59
|
+
export SENTISENSE_API_KEY=<your key> # or: npx -y sentisense@latest auth <your key>
|
|
60
|
+
npx -y sentisense@latest quote NVDA
|
|
61
|
+
npx -y sentisense@latest health # checks your key and the connection
|
|
63
62
|
```
|
|
64
63
|
|
|
65
|
-
### Commands
|
|
66
|
-
|
|
67
64
|
| Command | What you get |
|
|
68
65
|
|---------|--------------|
|
|
69
|
-
| `auth [key]` | Store a key, show what
|
|
70
|
-
| `init` | A temporary key with no signup,
|
|
71
|
-
| `health` |
|
|
72
|
-
| `quote <ticker>...` | Price, day
|
|
73
|
-
| `sentiment <ticker>` | SentiSense Score, tone, attention
|
|
74
|
-
| `mood` |
|
|
75
|
-
| `analysts <ticker>` | Consensus, price
|
|
76
|
-
| `analyst <slug>` | One analyst
|
|
77
|
-
| `earnings [ticker]` |
|
|
78
|
-
| `kpis <ticker>` | Company KPIs from earnings filings
|
|
79
|
-
| `insiders <ticker>` |
|
|
80
|
-
| `insights <ticker>` |
|
|
81
|
-
| `congress [ticker]` |
|
|
82
|
-
| `news [ticker]` |
|
|
83
|
-
| `flows [ticker]` |
|
|
84
|
-
| `options <ticker>` | End-of-day options positioning
|
|
85
|
-
| `screen --filter ...` | Screen
|
|
86
|
-
| `search <name>` |
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
`
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
npx -y sentisense@latest init # prints SENTISENSE_API_KEY=<key>, a command to try, and a keep link
|
|
96
|
-
npx -y sentisense@latest init --json # the same, as JSON
|
|
97
|
-
```
|
|
98
|
-
|
|
99
|
-
Right after the key, `init` prints one command to run next:
|
|
100
|
-
|
|
101
|
-
```bash
|
|
102
|
-
npx sentisense sentiment TSLA --api-key <key>
|
|
103
|
-
```
|
|
104
|
-
|
|
105
|
-
Tesla is a sample company, so the temporary key gets its full sentiment reading. `--api-key` applies to that one call, so it works before the key is stored anywhere. With `--json`, the same line is in `starterCommand`.
|
|
106
|
-
|
|
107
|
-
It prints a temporary free key as `SENTISENSE_API_KEY=<key>`. Store it the way your project already stores secrets; the SDK and every command read `SENTISENSE_API_KEY` from the environment. To keep the key, open the link it prints, sign in or create a free account, and the same key stays on your account with nothing else to change. Until it is kept, the key stops working after a few days and has request limits; the link still keeps it for about two weeks. When a key is already configured, `init` says so and makes no new one; `--new` asks for a fresh temporary key anyway. To tell machines that share a network apart, the request carries a random per-install id, stored as `install-id` in the CLI's config directory; it identifies nothing about you.
|
|
108
|
-
|
|
109
|
-
Three of these chain into each other. Start from a name, land on a person:
|
|
110
|
-
|
|
111
|
-
```bash
|
|
112
|
-
npx -y sentisense@latest search Tesla --type company # "Tesla" -> TSLA, plus the entity slug
|
|
113
|
-
npx -y sentisense@latest analysts NVDA --coverage # who covers it, by firm, with analyst slugs
|
|
114
|
-
npx -y sentisense@latest analyst quinn-bolton --calls # that analyst's firms, book, and notes
|
|
115
|
-
```
|
|
116
|
-
|
|
117
|
-
`analyst` takes a slug, not a name: slugs are lowercase and hyphenated, and every named analyst in a `--coverage` row carries the one that addresses them. A name is rejected before a request is spent. What comes back is call history, not accuracy scoring: there is no hit rate, no ranking, and nothing in it rates the person.
|
|
118
|
-
|
|
119
|
-
Ranking on `search` is the API's own, and a company can sort below its own products, so pass `--type company` when what you want is the issuer.
|
|
120
|
-
|
|
121
|
-
### Output modes
|
|
122
|
-
|
|
123
|
-
Readable in a terminal, plain text when piped, and exact API JSON on request:
|
|
124
|
-
|
|
125
|
-
```bash
|
|
126
|
-
npx -y sentisense@latest quote NVDA # terminal layout
|
|
127
|
-
npx -y sentisense@latest quote NVDA | cat # plain text, no escape codes
|
|
128
|
-
npx -y sentisense@latest quote NVDA --json | jq # the API response untouched
|
|
129
|
-
```
|
|
130
|
-
|
|
131
|
-
`--json` prints what the API returned, envelope and all, so `isPreview` and `totalCount` stay visible. For `quote` that is the exact quote response for one ticker, and an object keyed by ticker for several. `--full` widens any command. `--no-color` and `NO_COLOR` drop the colour, `--plain` and `--pretty` force a layout, and `--debug` prints stack traces.
|
|
132
|
-
|
|
133
|
-
Commands spend requests on the answer, not on decoration: `quote` looks up the company name only for the terminal layout, so piped and `--json` output cost one request per ticker. When something supplementary does not come back, such as the Score history behind a sparkline, the command still prints its answer and exits 0 with a `note:` line on stderr, so stdout stays clean for a pipe and the gap is never silent.
|
|
134
|
-
|
|
135
|
-
### Exit codes
|
|
136
|
-
|
|
137
|
-
Failures print two lines to stderr, what went wrong and what to do about it, and exit with a code you can branch on. The CLI does not retry, so a 5 is yours to handle.
|
|
66
|
+
| `auth [key]` | Store a key, show what's configured, or `--remove` it |
|
|
67
|
+
| `init` | A temporary key with no signup, and a link to keep it |
|
|
68
|
+
| `health` | Whether the API is reachable and your key works |
|
|
69
|
+
| `quote <ticker>...` | Price, day and 52-week range, market cap, P/E |
|
|
70
|
+
| `sentiment <ticker>` | SentiSense Score, tone, attention and the split by source |
|
|
71
|
+
| `mood` | Market Mood and the sector map |
|
|
72
|
+
| `analysts <ticker>` | Consensus, price targets, recent upgrades and downgrades. `--coverage` lists who covers it |
|
|
73
|
+
| `analyst <slug>` | One analyst's firms and coverage. `--calls` for their notes |
|
|
74
|
+
| `earnings [ticker]` | The calendar, or one company's quarters |
|
|
75
|
+
| `kpis <ticker>` | Company KPIs from earnings filings |
|
|
76
|
+
| `insiders <ticker>` | Form 4 trades, including whether they were pre-planned |
|
|
77
|
+
| `insights <ticker>` | Signals for a stock |
|
|
78
|
+
| `congress [ticker]` | Trades disclosed by members of Congress |
|
|
79
|
+
| `news [ticker]` | Stories with impact and tone |
|
|
80
|
+
| `flows [ticker]` | 13F flows, or one stock's holders |
|
|
81
|
+
| `options <ticker>` | End-of-day options positioning. `--intraday` for the latest session's 15-minute series (PRO) |
|
|
82
|
+
| `screen --filter ...` | Screen stocks on Score, analysts, technicals, price and options |
|
|
83
|
+
| `search <name>` | Turn a name into a ticker and entity slug |
|
|
84
|
+
|
|
85
|
+
`sentisense help <command>` shows the flags and examples for each one.
|
|
86
|
+
|
|
87
|
+
**A key with no signup.** `npx -y sentisense@latest init` prints `SENTISENSE_API_KEY=<key>` and a command to try it with. The key is temporary and rate-limited. To keep it, open the link it prints and sign in or create a free account; the same key then stays yours. `init` writes nothing into your project, and if a key is already configured it says so instead of making a new one. To tell apart machines that share a network, `init` sends a random id and stores it as `install-id` in the CLI's config directory (`~/.config/sentisense`). It is not derived from you or your machine.
|
|
88
|
+
|
|
89
|
+
**Output.** Commands print a readable layout in a terminal and plain text when piped. `--json` prints the API's JSON, under one key per call when a command makes several, so `isPreview` and `totalCount` are still there for `jq`. `--full` shows every column. In `quote NVDA ZZZZQ AAPL`, a ticker that fails is named on stderr and the rest still print, with that ticker's exit code.
|
|
90
|
+
|
|
91
|
+
Exit codes:
|
|
138
92
|
|
|
139
93
|
| Code | Meaning |
|
|
140
94
|
|------|---------|
|
|
@@ -143,55 +97,32 @@ Failures print two lines to stderr, what went wrong and what to do about it, and
|
|
|
143
97
|
| 2 | Bad usage: unknown command, flag, or missing argument |
|
|
144
98
|
| 3 | Missing or rejected API key |
|
|
145
99
|
| 4 | No data for that symbol or identifier |
|
|
146
|
-
| 5 | Rate limited |
|
|
100
|
+
| 5 | Rate limited, or the monthly allowance is used up (the CLI doesn't retry) |
|
|
147
101
|
| 6 | Network failure or timeout |
|
|
148
102
|
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
If you set `SENTISENSE_AGENT_NAME` (what your agent is called) and `SENTISENSE_SKILL` (the slug of the skill driving it), requests carry that identity, so usage can be understood and the tools improved. Both are optional, never required, and nothing is inferred when they are absent.
|
|
152
|
-
|
|
153
|
-
```bash
|
|
154
|
-
export SENTISENSE_AGENT_NAME=research-desk
|
|
155
|
-
export SENTISENSE_SKILL=us-stocks-analysis
|
|
156
|
-
npx -y sentisense@latest quote NVDA
|
|
157
|
-
# User-Agent: sentisense-node/{version} sentisense-cli/{version} (us-stocks-analysis; agent/research-desk)
|
|
158
|
-
```
|
|
159
|
-
|
|
160
|
-
Either can also be a flag (`--agent`, `--skill`) or a stored setting (`sentisense auth --agent research-desk --skill us-stocks-analysis`), resolved flag first, then environment, then config. Values are reduced to letters, digits, dot, underscore and hyphen, and capped at 32 characters, so nothing you set can reshape the header.
|
|
161
|
-
|
|
162
|
-
Research data, not investment advice.
|
|
103
|
+
If an agent drives the CLI, set `SENTISENSE_AGENT_NAME` and `SENTISENSE_SKILL` (or pass `--agent` and `--skill`) and requests carry them in the User-Agent.
|
|
163
104
|
|
|
164
105
|
## Configuration
|
|
165
106
|
|
|
166
107
|
```typescript
|
|
167
|
-
const client = new SentiSense({
|
|
168
|
-
apiKey: process.env.SENTISENSE_API_KEY, // Get yours at app.sentisense.ai/get-api-key
|
|
169
|
-
baseUrl: "https://...", // Default: https://app.sentisense.ai
|
|
170
|
-
timeout: 30000, // Default: 30s (in milliseconds)
|
|
171
|
-
maxRetries: 3, // Default: 3
|
|
172
|
-
userAgentSuffix: "my-bot/1.4", // Default: none
|
|
173
|
-
});
|
|
108
|
+
const client = new SentiSense({ timeout: 30000, maxRetries: 3 });
|
|
174
109
|
```
|
|
175
110
|
|
|
176
111
|
| Option | Default | What it does |
|
|
177
112
|
|--------|---------|--------------|
|
|
178
|
-
| `apiKey` | `SENTISENSE_API_KEY`
|
|
179
|
-
| `baseUrl` | `https://app.sentisense.ai` |
|
|
180
|
-
| `timeout` | `30000` |
|
|
181
|
-
| `maxRetries` | `3` | Retries the per-minute 429 and
|
|
182
|
-
| `userAgentSuffix` | none |
|
|
183
|
-
|
|
184
|
-
`userAgentSuffix` is how you say what is calling on top of the SDK, so your traffic is legible in your own logs and in ours. A tool name and version works (`"my-bot/1.4"`), optionally with an agent label (`"my-bot/1.4 agent/research-desk"`). Node only, since browsers set the header themselves. Newlines are collapsed and an empty value is ignored.
|
|
113
|
+
| `apiKey` | `SENTISENSE_API_KEY` | Your key, sent as the `X-SentiSense-API-Key` header |
|
|
114
|
+
| `baseUrl` | `https://app.sentisense.ai` | Change it only to point at another host |
|
|
115
|
+
| `timeout` | `30000` | Milliseconds per request |
|
|
116
|
+
| `maxRetries` | `3` | Retries for the per-minute 429 and server errors. Set `0` to handle them yourself |
|
|
117
|
+
| `userAgentSuffix` | none | Added to the User-Agent, such as `"my-bot/1.4"`, so your traffic is easy to spot in logs (Node only) |
|
|
185
118
|
|
|
186
|
-
Keep the key in the environment rather than in
|
|
119
|
+
Keep the key in the environment rather than in your code, so it never lands in git.
|
|
187
120
|
|
|
188
121
|
## Response shapes
|
|
189
122
|
|
|
190
|
-
Most methods resolve to the
|
|
123
|
+
Most methods resolve to the data itself. Two kinds of response wrap it, and the return types say which, so `.data` and `.documents` type-check without a cast.
|
|
191
124
|
|
|
192
|
-
**1. Tier-gated endpoints return a preview envelope.** The payload is in `data
|
|
193
|
-
|
|
194
|
-
Affected: every method whose declared return type is `PreviewResponse<T>`. A test keeps this table in step with the source, so it is the full list rather than a sample.
|
|
125
|
+
**1. Tier-gated endpoints return a preview envelope.** The payload is in `data`. `isPreview` says whether your plan got a shortened version, and `totalCount` is the full size when the server knows it. These are the methods that return it:
|
|
195
126
|
|
|
196
127
|
| Namespace | Methods |
|
|
197
128
|
|-----------|---------|
|
|
@@ -206,615 +137,309 @@ Affected: every method whose declared return type is `PreviewResponse<T>`. A tes
|
|
|
206
137
|
| `politicians` | `getActivity` `getFilings` `getMembers` `getMember` |
|
|
207
138
|
| `stocks` | `getSentiment` `getKpis` `getOptionsSummary` `getOptionsHistory` `getOptionsIntradayHistory` |
|
|
208
139
|
|
|
209
|
-
The envelope itself is always an object, so test the payload rather than the response. Three of these declare a `data` that can be null: `stocks.getOptionsSummary`, for a ticker outside the covered options universe, `options.getOverview`, before its first nightly build, and `stocks.getOptionsIntradayHistory`, on a FREE key's `PRO_REQUIRED` preview. Everywhere else `data` is an array or an object.
|
|
210
|
-
|
|
211
140
|
```typescript
|
|
212
141
|
const flows = await client.institutional.getFlows();
|
|
213
|
-
if (flows.isPreview) {
|
|
214
|
-
|
|
215
|
-
}
|
|
216
|
-
for (const flow of flows.data.inflows) {
|
|
217
|
-
console.log(flow.ticker, flow.netSharesChange);
|
|
218
|
-
}
|
|
219
|
-
|
|
220
|
-
// holders nest one level deeper: ticker-level totals plus the rows
|
|
221
|
-
const holders = await client.institutional.getHolders("AAPL", "2026-06-30");
|
|
222
|
-
console.log(`${holders.data.holderCount} holders`);
|
|
223
|
-
const newPositions = holders.data.holders.filter((h) => h.changeType === "NEW");
|
|
224
|
-
|
|
225
|
-
// insights use the same envelope, wrapping a plain array
|
|
226
|
-
const insights = await client.insights.stock("AAPL");
|
|
227
|
-
for (const insight of insights.data) {
|
|
228
|
-
console.log(insight.insightText);
|
|
229
|
-
}
|
|
142
|
+
if (flows.isPreview) console.log(`Preview: ${flows.data.inflows.length} of ${flows.totalCount}`);
|
|
143
|
+
for (const flow of flows.data.inflows) console.log(flow.ticker, flow.netSharesChange);
|
|
230
144
|
```
|
|
231
145
|
|
|
232
|
-
|
|
146
|
+
The envelope is always an object, so test `data`, not the response. `data` can be `null` on three of them: `stocks.getOptionsSummary` for an uncovered ticker, `options.getOverview` before its first nightly build, and `stocks.getOptionsIntradayHistory` on a free key.
|
|
233
147
|
|
|
234
|
-
|
|
148
|
+
**2. Document endpoints return a search wrapper.** The rows are in `documents`, next to `totalCount`, with no preview flag. That covers `documents.getByTicker`, `getByTickerRange`, `getByEntity`, `search` and `getBySource`. `stocks.getFundamentalsPeriods` puts its rows in `periods`.
|
|
235
149
|
|
|
236
|
-
|
|
237
|
-
const results = await client.documents.search("NVDA earnings", { days: 7 });
|
|
238
|
-
console.log(`${results.totalCount} matches`);
|
|
239
|
-
for (const doc of results.documents) {
|
|
240
|
-
console.log(doc.url, doc.averageSentiment);
|
|
241
|
-
}
|
|
242
|
-
```
|
|
243
|
-
|
|
244
|
-
Everything else, including `stocks.getPrice()`, `documents.getStories()`, `insights.types()` and `institutional.getQuarters()`, resolves to the value itself with no wrapper.
|
|
245
|
-
|
|
246
|
-
> **Upgrading from 0.28.x or earlier?** These return types were corrected in 0.29.0. If your code read the flat shape (`flows.inflows`, `holders.filter(...)`), it was returning `undefined` / throwing at runtime already; switch to `flows.data.inflows` / `holders.data.holders`. See [CHANGELOG.md](./CHANGELOG.md) for the full mapping.
|
|
150
|
+
[Using the Python and Node SDKs](https://sentisense.ai/docs/support/using-the-python-and-node-sdks/) covers previews, paging, retries and errors for both SDKs.
|
|
247
151
|
|
|
248
152
|
## API reference
|
|
249
153
|
|
|
154
|
+
Each section lists the calls and links to the API docs page that explains every field.
|
|
155
|
+
|
|
250
156
|
### Stocks
|
|
251
157
|
|
|
252
158
|
```typescript
|
|
253
|
-
client.stocks.list()
|
|
254
|
-
client.stocks.listDetailed()
|
|
255
|
-
client.stocks.
|
|
256
|
-
client.stocks.
|
|
257
|
-
client.stocks.
|
|
258
|
-
client.stocks.
|
|
259
|
-
client.stocks.
|
|
260
|
-
client.stocks.
|
|
261
|
-
client.stocks.
|
|
262
|
-
client.stocks.
|
|
263
|
-
client.stocks.
|
|
264
|
-
client.stocks.
|
|
265
|
-
client.stocks.
|
|
266
|
-
client.stocks.
|
|
267
|
-
client.stocks.
|
|
268
|
-
client.stocks.
|
|
269
|
-
client.stocks.
|
|
270
|
-
client.stocks.
|
|
271
|
-
client.stocks.
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
Short interest and short volume come back newest first, and an unknown ticker returns an empty `dataPoints` array rather than an error. Every identifier in `getGraph` is a slug, the same handle the metric and document endpoints take. An ETF symbol is refused by `getQuote` with an `APIError` whose `code` is `"ticker_is_etf"`; use `etfs.quote()` for funds.
|
|
279
|
-
|
|
280
|
-
Product nodes (`type === "PRODUCT_OR_SERVICE"`) in `stocks.getGraph` now carry optional `category` when known. Other nodes and products without a category omit it.
|
|
159
|
+
client.stocks.list() // every ticker we cover
|
|
160
|
+
client.stocks.listDetailed() // the same, with names and entity ids
|
|
161
|
+
client.stocks.listPopular() // the most-followed tickers
|
|
162
|
+
client.stocks.getPrice("AAPL") // latest price, delayed 15 minutes
|
|
163
|
+
client.stocks.getPrices(["AAPL", "NVDA"]) // several at once
|
|
164
|
+
client.stocks.getQuote("AAPL") // day range, 52-week range, market cap, P/E
|
|
165
|
+
client.stocks.getProfile("AAPL") // company profile
|
|
166
|
+
client.stocks.getChart("AAPL", { timeframe: "6M" }) // price bars
|
|
167
|
+
client.stocks.getMarketStatus() // is the market open
|
|
168
|
+
client.stocks.getSimilar("AAPL") // peers
|
|
169
|
+
client.stocks.getEtfs("NVDA", { limit: 5 }) // ETFs that hold it, heaviest weight first
|
|
170
|
+
client.stocks.getGraph("AAPL", { depth: 1 }) // people, products and peers
|
|
171
|
+
client.stocks.getEntities("AAPL") // entities linked to the stock
|
|
172
|
+
client.stocks.getAISummary("AAPL", { depth: "deep" }) // our research report
|
|
173
|
+
client.stocks.getFundamentals("AAPL") // statements, as filed
|
|
174
|
+
client.stocks.getFundamentalsHistory("AAPL", { timeframe: "annual" }) // up to 40 quarters or 20 years
|
|
175
|
+
client.stocks.getCurrentFundamentals("AAPL") // the latest snapshot
|
|
176
|
+
client.stocks.getShortInterest("GME", { limit: 12 }) // short interest by settlement date
|
|
177
|
+
client.stocks.getShortVolume("GME") // daily short volume
|
|
178
|
+
client.stocks.getFloat("GME") // shares available to trade
|
|
179
|
+
client.stocks.getImages(["AAPL"]) // logos
|
|
180
|
+
client.stocks.getDescriptions(["AAPL"]) // short company descriptions
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
For a fund, use `etfs.quote()`. `getQuote` accepts a fund ticker but leaves out AUM, NAV and expense ratio, and its `seeInstead` points at the fund quote. Only the `10Y` and `MAX` charts are dividend-adjusted. Statement figures are in the company's own currency (`reportedCurrency`); a period served from an SEC-backed record says which lines came from the filing in `source` and `lineSources`. [Stocks API docs](https://sentisense.ai/docs/api/stocks/)
|
|
281
184
|
|
|
282
185
|
### Documents & news
|
|
283
186
|
|
|
284
187
|
```typescript
|
|
285
|
-
client.documents.getByTicker("AAPL", { source: "news", days: 3 })
|
|
286
|
-
client.documents.search("NVDA earnings", { days: 7, limit: 20 })
|
|
287
|
-
client.documents.getStories({ limit: 10 })
|
|
288
|
-
client.documents.
|
|
289
|
-
client.documents.
|
|
188
|
+
client.documents.getByTicker("AAPL", { source: "news", days: 3 }) // news and social posts about a stock
|
|
189
|
+
client.documents.search("NVDA earnings", { days: 7, limit: 20 }) // plain-language search
|
|
190
|
+
client.documents.getStories({ limit: 10 }) // today's stories
|
|
191
|
+
client.documents.getStoriesByTicker("AAPL", { limit: 5 }) // stories about one stock
|
|
192
|
+
client.documents.searchStories({ query: "fed decision", days: 30 }) // search stories
|
|
193
|
+
client.documents.getStoryDetail("cluster_abc123") // one story in full
|
|
194
|
+
client.marketSummary.get() // our written market summary
|
|
290
195
|
```
|
|
291
196
|
|
|
292
|
-
|
|
293
|
-
`"ORIGINAL"` for an editorially authored SentiSense Original and `"AI"` for a
|
|
294
|
-
pipeline-generated story, and `isLive` is true while the story is still being revised as
|
|
295
|
-
the event develops. Both are optional: against an API build that predates them they are
|
|
296
|
-
`undefined`, which means "not known" rather than `"AI"` or `false`.
|
|
197
|
+
Documents carry sentiment, entities and a link, not the article text. `getStoryDetail` returns `unknown`, so narrow it yourself; `StoryTimelineEntry` types its `timeline`. [Documents API docs](https://sentisense.ai/docs/api/documents/)
|
|
297
198
|
|
|
298
|
-
|
|
299
|
-
plus a `timeline` array of dated updates, newest first and empty when a story has none.
|
|
300
|
-
The `StoryTimelineEntry` type is exported for that array:
|
|
199
|
+
### Entity metrics
|
|
301
200
|
|
|
302
201
|
```typescript
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
for (const update of detail.timeline) {
|
|
309
|
-
console.log(new Date(update.publishedAt), update.updateType, update.content);
|
|
310
|
-
}
|
|
202
|
+
client.entityMetrics.getMetrics("AAPL", { metricType: "sentiment" }) // one metric over time
|
|
203
|
+
client.entityMetrics.getMetrics("AAPL", { metricType: "mentions", startTime: Date.now() - 7 * 86400000 })
|
|
204
|
+
client.entityMetrics.getDistribution("AAPL", "mentions", { dimension: "source" }) // share of mentions by source, valueType "SHARE_PERCENT"
|
|
205
|
+
client.entityMetrics.getDistribution("AAPL", "sentiment") // mean sentiment by source, valueType "MEAN"
|
|
206
|
+
client.stocks.getSentiment("AAPL") // Score, mentions, tone by source
|
|
311
207
|
```
|
|
312
208
|
|
|
313
|
-
|
|
209
|
+
Available metric types: `mentions`, `sentiment`, `sentisense_score`, `sentisense_rating`, `social_dominance`, `creators`, `app_review_count`, `app_rating`, `app_all_ratings_count`, `app_all_ratings_avg`. The `app_` ones take a product slug such as `"Instagram"`, not a ticker.
|
|
314
210
|
|
|
315
|
-
|
|
316
|
-
client.institutional.getQuarters()
|
|
317
|
-
client.institutional.getFlows("2025-02-14", { limit: 20 })
|
|
318
|
-
client.institutional.getHolders("AAPL", "2025-02-14")
|
|
319
|
-
client.institutional.getHolders("AAPL") // no date: the ticker's latest settled quarter
|
|
320
|
-
client.institutional.getHoldersHistory("AAPL", { quarters: 8 })
|
|
321
|
-
client.institutional.getInstitutionDetail("Berkshire-Hathaway", { limit: 10, sortBy: "estimatedFlowUsd" })
|
|
322
|
-
client.institutional.getInstitutionHistory("Renaissance-Technologies", { quarters: 8, tickers: ["NVDA"] })
|
|
323
|
-
client.institutional.getActivists("2025-02-14")
|
|
324
|
-
```
|
|
211
|
+
Sentiment runs from -1 to 1. The SentiSense Score is sentiment weighted by attention and has no fixed range. Each point's reading is in `value`. `startTime` and `endTime` are epoch milliseconds. [Metrics API docs](https://sentisense.ai/docs/api/metrics/)
|
|
325
212
|
|
|
326
|
-
|
|
213
|
+
### SentiSense Rating
|
|
327
214
|
|
|
328
215
|
```typescript
|
|
329
|
-
const
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
console.log(
|
|
216
|
+
const rating = await client.stocks.getRating("AAPL");
|
|
217
|
+
if (rating.rated) {
|
|
218
|
+
console.log(rating.letter, rating.score, "percentile", rating.percentile);
|
|
219
|
+
} else {
|
|
220
|
+
console.log("no grade today:", rating.reason);
|
|
334
221
|
}
|
|
335
222
|
```
|
|
336
223
|
|
|
337
|
-
|
|
224
|
+
`rated` narrows the type, so check it first: an unrated stock comes back as a normal response. Each response carries a `disclaimer` to show next to the grade. [Rating API docs](https://sentisense.ai/docs/api/sentisense-rating/)
|
|
338
225
|
|
|
339
|
-
|
|
340
|
-
first, covering the 12 newest quarters by default (`quarters` up to 20). Free keys see the
|
|
341
|
-
newest four. The newest row can still be filing (`status: "filing"`), in which case it covers
|
|
342
|
-
only the institutions that have filed so far. `sharesOutstanding`, `institutionalOwnershipPct`,
|
|
343
|
-
`avgClosePrice` and `dollarFlowUsd` are absent when they cannot be computed, never zero:
|
|
226
|
+
### Insights
|
|
344
227
|
|
|
345
228
|
```typescript
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
229
|
+
client.insights.stock("AAPL") // signals for one stock
|
|
230
|
+
client.insights.market() // market-wide signals
|
|
231
|
+
client.insights.latest() // the newest across every stock; free keys get the top 5
|
|
232
|
+
client.insights.types("AAPL") // which signal types exist for a stock
|
|
350
233
|
```
|
|
351
234
|
|
|
352
|
-
|
|
353
|
-
`max(0, holdingsCount - soldOutPositions)`, even when the holdings list is truncated.
|
|
354
|
-
`getInstitutionDetail` keeps its `Promise<unknown>` signature. The exported all-optional
|
|
355
|
-
`InstitutionDetail` type is available for callers who want to opt in:
|
|
235
|
+
[Insights API docs](https://sentisense.ai/docs/api/insights/)
|
|
356
236
|
|
|
357
|
-
|
|
358
|
-
import type { InstitutionDetail, PreviewResponse } from "sentisense";
|
|
359
|
-
|
|
360
|
-
const detail = await client.institutional.getInstitutionDetail("1067983") as PreviewResponse<InstitutionDetail>;
|
|
361
|
-
console.log(detail.data.positionsHeld); // undefined when an older response omits it
|
|
362
|
-
```
|
|
363
|
-
|
|
364
|
-
Institution detail compares each filing with the quarter before it. When `comparisonStatus` is `AVAILABLE`, the payload carries `priorTotalValueUsd` and `priorPositionsHeld`, and each holding carries `priorValueUsd`, `priorPortfolioWeight` and `estimatedFlowUsd` (dollars bought, positive, or sold, negative, estimated from two quarter-end snapshots rather than a reported trade). Every one of these is absent when it does not apply. Pass `limit` to get a sorted page of holdings, with `sortBy`, `sortDir`, `changeType` (a value or an array; `"HELD"` keeps every position still held, whatever its change), `q` and `minWeight` to sort and filter it; those only take effect together with `limit`. When a filter is set, `data.matchTotals` sums every matching holding, not just the page:
|
|
365
|
-
|
|
366
|
-
```typescript
|
|
367
|
-
// The ten biggest estimated buys of the latest quarter
|
|
368
|
-
const page = await client.institutional.getInstitutionDetail("Berkshire-Hathaway", {
|
|
369
|
-
limit: 10,
|
|
370
|
-
sortBy: "estimatedFlowUsd",
|
|
371
|
-
changeType: ["NEW", "INCREASED"],
|
|
372
|
-
}) as PreviewResponse<InstitutionDetail>;
|
|
373
|
-
for (const h of page.data.holdings ?? []) console.log(h.ticker, h.estimatedFlowUsd);
|
|
374
|
-
console.log(page.data.matchTotals?.estimatedFlowUsd); // every matching holding, not only these ten
|
|
375
|
-
```
|
|
376
|
-
|
|
377
|
-
**Institution history.** `getInstitutionHistory()` returns one row per filing, newest first (`quarters` up to 40, 12 by default). Free keys see the newest four, with `totalCount` naming the window. The comparison fields (`newPositions`, `boughtUsd`, `netFlowUsd` and the rest) are absent unless that filing's `comparisonStatus` is `AVAILABLE`, never zero. Pass `tickers` (up to 100) to also get `positions`: each ticker's shares and value per filing, newest first, with filings where the institution did not hold it left out. Free keys receive `positions` only for the institution's ten largest holdings. `priceEffectUsd` is the remainder after `netFlowUsd`, mostly price moves; it also absorbs rounding, the different price bases of exits and trades, and positions whose change could not be restated:
|
|
237
|
+
### Insider trading (Form 4)
|
|
378
238
|
|
|
379
239
|
```typescript
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
});
|
|
384
|
-
for (const q of data.quarters) {
|
|
385
|
-
console.log(q.label, q.totalValueUsd, q.netFlowUsd, q.priceEffectUsd);
|
|
386
|
-
}
|
|
387
|
-
for (const point of data.positions?.NVDA ?? []) {
|
|
388
|
-
console.log(point.reportDate, point.shares, point.valueUsd);
|
|
389
|
-
}
|
|
240
|
+
client.insider.getActivity({ lookbackDays: 30 }) // buying and selling across the market
|
|
241
|
+
client.insider.getTrades("NVDA", { lookbackDays: 90 }) // each filed trade in one stock
|
|
242
|
+
client.insider.getClusterBuys({ lookbackDays: 90 }) // three or more insiders buying the same stock
|
|
390
243
|
```
|
|
391
244
|
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
| Option | Values |
|
|
395
|
-
|--------|--------|
|
|
396
|
-
| `limit` | Maximum rows to return. Must be >= 1; values above 1000 are capped server-side. Omit for the full list. |
|
|
397
|
-
| `offset` | Row offset to start from. Server default is 0. Requires `limit`. |
|
|
398
|
-
| `sortBy` | `"shares"` (server default), `"valueUsd"`, or `"sharesChangePct"`. Requires `limit`. |
|
|
399
|
-
| `sortDir` | `"desc"` (server default) or `"asc"`. Requires `limit`. |
|
|
245
|
+
Count real buying and selling by `transactionCode` (`P` and `S` are open-market trades). `transactionType` also labels shares withheld for taxes, code `F`, as `SELL`. [Insider API docs](https://sentisense.ai/docs/api/insider-trading/)
|
|
400
246
|
|
|
401
|
-
|
|
247
|
+
### Options
|
|
402
248
|
|
|
403
249
|
```typescript
|
|
404
|
-
//
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
sortDir: "desc",
|
|
409
|
-
});
|
|
410
|
-
for (const holder of top.data.holders) {
|
|
411
|
-
console.log(holder.filerName, holder.valueUsd);
|
|
412
|
-
}
|
|
413
|
-
|
|
414
|
-
// Walk the list a page at a time
|
|
415
|
-
const page = await client.institutional.getHolders("AAPL", "2026-03-31", {
|
|
416
|
-
limit: 100,
|
|
417
|
-
offset: 100,
|
|
418
|
-
});
|
|
419
|
-
console.log(`${page.data.holders.length} rows of ${page.data.holderCount}`);
|
|
250
|
+
client.options.getOverview() // where options activity is unusual today
|
|
251
|
+
client.stocks.getOptionsSummary("NVDA") // one stock's options picture
|
|
252
|
+
client.stocks.getOptionsHistory("NVDA", { window: "2y" }) // the same readings as a daily series
|
|
253
|
+
client.stocks.getOptionsIntradayHistory("NVDA") // every 15-minute reading from one session (PRO)
|
|
420
254
|
```
|
|
421
255
|
|
|
422
|
-
|
|
256
|
+
Apart from the intraday history, these are end-of-day readings, each measured against the stock's own past year. The overview ranks stocks and ETFs separately. For an uncovered ticker, `getOptionsSummary` returns `data: null`. [Options API docs](https://sentisense.ai/docs/api/options/)
|
|
423
257
|
|
|
424
258
|
### Congressional trading
|
|
425
259
|
|
|
426
260
|
```typescript
|
|
427
|
-
client.politicians.getActivity({ lookbackDays: 90 })
|
|
428
|
-
client.politicians.getFilings("NVDA")
|
|
429
|
-
client.politicians.getMembers()
|
|
430
|
-
client.politicians.getMember("nancy-pelosi")
|
|
431
|
-
client.politicians.getDirectory({ q: "tex" })
|
|
261
|
+
client.politicians.getActivity({ lookbackDays: 90 }) // recent disclosed trades
|
|
262
|
+
client.politicians.getFilings("NVDA") // trades in one stock
|
|
263
|
+
client.politicians.getMembers() // members in office, with trading stats
|
|
264
|
+
client.politicians.getMember("nancy-pelosi") // one member's profile and trades
|
|
265
|
+
client.politicians.getDirectory({ q: "tex" }) // find a slug, including former members
|
|
432
266
|
```
|
|
433
267
|
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
| Option | Values |
|
|
437
|
-
|--------|--------|
|
|
438
|
-
| `lookbackDays` | Days to look back (1-365). Defaults to 90. |
|
|
439
|
-
| `limit` | Rows to return. Must be >= 1; anything above 500 is capped at 500. Omit for the default 200. |
|
|
440
|
-
| `offset` | Row offset to start from. Defaults to 0. Works with or without `limit`. |
|
|
268
|
+
The activity feed returns 200 rows unless you pass `limit`, so walk it with `offset` until you reach `totalCount`:
|
|
441
269
|
|
|
442
270
|
```typescript
|
|
443
271
|
const first = await client.politicians.getActivity({ limit: 100 });
|
|
444
272
|
console.log(`${first.data.length} of ${first.totalCount} disclosures`);
|
|
445
|
-
|
|
446
|
-
for (let offset = 100; offset < (first.totalCount ?? 0); offset += 100) {
|
|
447
|
-
const page = await client.politicians.getActivity({ limit: 100, offset });
|
|
448
|
-
for (const trade of page.data) {
|
|
449
|
-
console.log(trade.politicianName, trade.ticker, trade.transactionType);
|
|
450
|
-
}
|
|
451
|
-
}
|
|
452
273
|
```
|
|
453
274
|
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
```typescript
|
|
457
|
-
client.insider.getActivity({ lookbackDays: 30 }) // Market-wide buys and sells by ticker
|
|
458
|
-
client.insider.getTrades("NVDA", { lookbackDays: 90 }) // Individual filed transactions
|
|
459
|
-
client.insider.getClusterBuys({ lookbackDays: 90 }) // 3+ distinct insiders buying the same stock
|
|
460
|
-
```
|
|
461
|
-
|
|
462
|
-
Each trade row carries both the raw SEC `transactionCode` and a simplified `transactionType`. Only codes `P` and `S` are open-market trades; awards, gifts, exercises, and code `F` (shares withheld to cover taxes at vest, served as `SELL`) are corporate mechanics, so read `transactionCode` when you tally discretionary buying or selling. The market-wide activity endpoint's sells already exclude code `F` server-side.
|
|
275
|
+
[Politicians API docs](https://sentisense.ai/docs/api/politicians/)
|
|
463
276
|
|
|
464
|
-
###
|
|
465
|
-
|
|
466
|
-
The price target cone (mean, high, low, upside %) and consensus are free for everyone with full data. Upgrade/downgrade feeds and forward EPS estimates are limited on free, unlimited on PRO.
|
|
277
|
+
### Institutional flows (13F)
|
|
467
278
|
|
|
468
279
|
```typescript
|
|
469
|
-
client.
|
|
470
|
-
client.
|
|
471
|
-
client.
|
|
472
|
-
client.
|
|
473
|
-
client.
|
|
474
|
-
client.
|
|
280
|
+
client.institutional.getQuarters() // the 13F quarters we hold, newest first
|
|
281
|
+
client.institutional.getFlows() // the latest quarter's biggest inflows and outflows
|
|
282
|
+
client.institutional.getHolders("AAPL", "2026-06-30", { limit: 25 }) // who holds a stock
|
|
283
|
+
client.institutional.getHoldersHistory("AAPL", { quarters: 8 }) // ownership quarter by quarter
|
|
284
|
+
client.institutional.listInstitutions() // find funds, largest first
|
|
285
|
+
client.institutional.getInstitutionDetail("Berkshire-Hathaway", { limit: 10, sortBy: "estimatedFlowUsd" })
|
|
286
|
+
client.institutional.getInstitutionHistory("Renaissance-Technologies", { quarters: 8, tickers: ["NVDA"] })
|
|
287
|
+
client.institutional.getActivists("2026-06-30") // activist positions for a quarter
|
|
475
288
|
```
|
|
476
289
|
|
|
477
|
-
|
|
290
|
+
The newest quarter is often incomplete, so pick one by its `pending` flag rather than taking the first. A widely held stock has thousands of holders, so pass `limit`; `offset`, `sortBy` and `sortDir` only work alongside it.
|
|
291
|
+
`getInstitutionDetail` returns `unknown`, so cast it to `PreviewResponse<InstitutionDetail>`; its sort and filter options also need `limit`.
|
|
478
292
|
|
|
479
293
|
```typescript
|
|
480
|
-
const
|
|
481
|
-
|
|
482
|
-
const {
|
|
483
|
-
|
|
484
|
-
console.log(`${row.actionDate} ${row.firm} cut its target from ${prior} to ${target}`);
|
|
485
|
-
}
|
|
294
|
+
const quarter = (await client.institutional.getQuarters()).find((q) => !q.pending)?.reportDate;
|
|
295
|
+
if (quarter) {
|
|
296
|
+
const top = await client.institutional.getHolders("AAPL", quarter, { limit: 10, sortBy: "valueUsd" });
|
|
297
|
+
for (const holder of top.data.holders) console.log(holder.filerName, holder.valueUsd);
|
|
486
298
|
}
|
|
487
299
|
```
|
|
488
300
|
|
|
489
|
-
|
|
301
|
+
[13F API docs](https://sentisense.ai/docs/api/institutional-flows/)
|
|
490
302
|
|
|
491
|
-
|
|
492
|
-
client.analyst.coverage("NVDA", { lookbackDays: 365 }) // Who covers it, by firm. Free: 5 firms.
|
|
493
|
-
client.analyst.profile("gil-luria") // One analyst's firms + coverage book.
|
|
494
|
-
client.analyst.calls("gil-luria", { limit: 25 }) // Their price target notes, newest first.
|
|
495
|
-
```
|
|
303
|
+
### Analyst ratings
|
|
496
304
|
|
|
497
305
|
```typescript
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
}
|
|
507
|
-
|
|
508
|
-
for (const row of book.coverage.slice(0, 5)) {
|
|
509
|
-
if (row.noteCount === 0) {
|
|
510
|
-
// A desk can cover a stock on rating actions alone, with no price target.
|
|
511
|
-
console.log(`${row.firm}: rating only, ${row.firmRating?.rating}`);
|
|
512
|
-
continue;
|
|
513
|
-
}
|
|
514
|
-
const who = row.latestNote?.analyst ?? "unattributed";
|
|
515
|
-
console.log(`${row.firm}: ${row.latestNote?.priceTarget} (${who})`);
|
|
516
|
-
|
|
517
|
-
for (const analyst of row.analysts) {
|
|
518
|
-
if (!analyst.slug) continue;
|
|
519
|
-
const calls = await client.analyst.calls(analyst.slug, { limit: 10 });
|
|
520
|
-
console.log(` ${analyst.name}: ${calls.totalCount} notes on record`);
|
|
521
|
-
}
|
|
522
|
-
}
|
|
306
|
+
client.analyst.consensus("AAPL") // price target range, analyst count, upside
|
|
307
|
+
client.analyst.consensusHistory("AAPL", { limit: 90 }) // the consensus day by day
|
|
308
|
+
client.analyst.calledIt("AAPL") // which analysts called the stock's big moves
|
|
309
|
+
client.analyst.actions("AAPL", { lookbackDays: 30 }) // upgrades and downgrades, with price targets
|
|
310
|
+
client.analyst.estimates("AAPL") // EPS estimates and past surprises
|
|
311
|
+
client.analyst.marketActivity({ lookbackDays: 7 }) // analyst actions across every stock
|
|
312
|
+
client.analyst.coverage("NVDA") // who covers a stock and what they said last
|
|
313
|
+
client.analyst.profile("gil-luria") // one analyst and the stocks they cover
|
|
314
|
+
client.analyst.calls("gil-luria", { limit: 25 }) // their price target notes, newest first
|
|
523
315
|
```
|
|
524
316
|
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
`ratingBuckets` sizes the same book by rating tier: `buy`, `hold`, `sell`, `unrated` and `total`, counted over every covering firm before the free truncation, so `buy + hold + sell + unrated === total` and a free key reads the same numbers as a PRO one. `unrated` is a desk with no current rating on record, such as a price-target-only firm. These count the firms in this coverage book, a different population from the `strongBuy` through `strongSell` figures on `client.analyst.consensus`, which come from the provider's analyst survey. Read one or the other, do not reconcile them.
|
|
528
|
-
|
|
529
|
-
Surprise rows now carry optional `surprisePct`, the signed true percent rounded half-up to two decimals: `(actualEps - estimateEps) * 100 / abs(estimateEps)`. It is `null` when either EPS is missing or the estimate is zero, and `undefined` on older responses. The existing `surprisePercent` fraction is unchanged (`0.03` means about 3%).
|
|
317
|
+
`priceTarget` and `priorPriceTarget` on action rows are `null` when the firm stated none, never zero. [Analyst API docs](https://sentisense.ai/docs/api/analyst-ratings/)
|
|
530
318
|
|
|
531
319
|
### Earnings
|
|
532
320
|
|
|
533
|
-
The earnings analysis report is the assembled version of a quarter: one object per fiscal period carrying the editorial headline, the KPI cards with year-over-year deltas, the guidance language as management phrased it, and a summary of the earnings call. Pair it with the recent-reporters feed to drive a post-earnings sweep. Summaries, recent reports, statistics, and rankings return the preview envelope; per-ticker reactions return a direct payload.
|
|
534
|
-
|
|
535
321
|
```typescript
|
|
536
|
-
client.
|
|
537
|
-
client.earnings.
|
|
538
|
-
client.earnings.
|
|
539
|
-
client.earnings.
|
|
540
|
-
client.earnings.
|
|
322
|
+
client.calendar.getEarnings() // upcoming report dates and estimates
|
|
323
|
+
client.earnings.getSummaries("AAPL", { limit: 4 }) // each quarter written up: headline, KPIs, guidance, call summary
|
|
324
|
+
client.earnings.getRecent({ days: 7 }) // who reported recently
|
|
325
|
+
client.earnings.getReactions("AAPL") // how the stock moved after its last reports
|
|
326
|
+
client.earnings.getStatistics({ window: "week_to_date" }) // beat rates and reactions across the market
|
|
327
|
+
client.earnings.getRanked({ reportedDays: 14, upcomingDays: 7 }) // the reports that mattered most
|
|
541
328
|
```
|
|
542
329
|
|
|
543
330
|
```typescript
|
|
544
|
-
const
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
if (quarter) {
|
|
548
|
-
console.log(quarter.fiscalPeriod, quarter.reportDate);
|
|
549
|
-
console.log(quarter.headline);
|
|
550
|
-
for (const kpi of quarter.kpiHighlights ?? []) {
|
|
551
|
-
console.log(` ${kpi.label}: ${kpi.value} (${kpi.yoy ?? "no YoY"})`);
|
|
552
|
-
}
|
|
553
|
-
|
|
554
|
-
if (res.isPreview) {
|
|
555
|
-
// Free key: section titles stand in for the bodies.
|
|
556
|
-
console.log("Summary covers:", quarter.summaryTopics?.join(", "));
|
|
557
|
-
} else {
|
|
558
|
-
console.log(quarter.summaryMd);
|
|
559
|
-
}
|
|
560
|
-
}
|
|
331
|
+
const [quarter] = (await client.earnings.getSummaries("AAPL", { limit: 1 })).data;
|
|
332
|
+
if (quarter) console.log(quarter.fiscalPeriod, quarter.headline);
|
|
561
333
|
```
|
|
562
334
|
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
`earnings.getSummaries` exposes optional `totalCount` on the envelope on both PRO and FREE. It counts indexed quarters; returned rows can be fewer because of `limit` or an unavailable body. Older responses without the count still read as `undefined`.
|
|
566
|
-
|
|
567
|
-
The envelope `ticker` names the listing the quarters' per-share figures are quoted for: `BRK-A` answers `BRK.B` and `GOOG` answers `GOOGL`. It reads `undefined` on older responses.
|
|
335
|
+
[Earnings API docs](https://sentisense.ai/docs/api/earnings/)
|
|
568
336
|
|
|
569
337
|
### Company KPIs (PRO)
|
|
570
338
|
|
|
571
|
-
Full data on 11 sample companies, free, with a preview for every other company: a free key reads the full series for the sample companies and metadata only for the rest, and PRO reads the full series for all. Check `sampleCompany` on a response, or `upgrade.sampleTickers` on a preview for the list. See [full sample responses](https://sentisense.ai/docs/api/#full-sample-responses-with-a-free-key).
|
|
572
|
-
|
|
573
339
|
```typescript
|
|
574
|
-
client.stocks.getKpis("TSLA")
|
|
575
|
-
client.stocks.listKpiCoverage()
|
|
340
|
+
client.stocks.getKpis("TSLA") // product and segment metrics over time, like Tesla deliveries
|
|
341
|
+
client.stocks.listKpiCoverage() // which companies have KPIs (free, no quota cost)
|
|
342
|
+
client.stocks.getKpiTypes("TSLA") // which KPIs a company has
|
|
576
343
|
```
|
|
577
344
|
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
Composition data is public; the holdings-weighted aggregate views follow the same PRO-with-preview pattern as analyst and insider data. Aggregates synthesize fund-level views from each constituent's per-stock data, weighted by allocation, with a `coverage` block on every response.
|
|
581
|
-
|
|
582
|
-
```typescript
|
|
583
|
-
client.etfs.list() // Every ETF tracked
|
|
584
|
-
client.etfs.quote("SPY") // Price, ranges, AUM, expense ratio, NAV
|
|
585
|
-
client.etfs.holdings("QQQ") // Full composition + freshness metadata
|
|
586
|
-
client.etfs.analystAggregate("QQQ") // Holdings-weighted analyst consensus
|
|
587
|
-
client.etfs.insiderAggregate("ARKK", { lookbackDays: 90 }) // Holdings-weighted Form 4 net flow
|
|
588
|
-
client.etfs.sentimentAggregate("QQQ") // Constituent-weighted vs direct Score
|
|
589
|
-
```
|
|
590
|
-
|
|
591
|
-
### Entity metrics
|
|
592
|
-
|
|
593
|
-
```typescript
|
|
594
|
-
// Time-series metrics (v2 API)
|
|
595
|
-
client.entityMetrics.getMetrics("AAPL", { metricType: "sentiment" })
|
|
596
|
-
client.entityMetrics.getMetrics("AAPL", {
|
|
597
|
-
metricType: "mentions",
|
|
598
|
-
startTime: Date.now() - 7 * 86400000,
|
|
599
|
-
endTime: Date.now(),
|
|
600
|
-
maxDataPoints: 100,
|
|
601
|
-
})
|
|
602
|
-
|
|
603
|
-
// Daily App Store ratings for a product entity with an app (an entity slug, not a ticker)
|
|
604
|
-
client.entityMetrics.getMetrics("Instagram", { metricType: "app_all_ratings_count" })
|
|
605
|
-
|
|
606
|
-
// Share of mentions by source (valueType "SHARE_PERCENT")
|
|
607
|
-
client.entityMetrics.getDistribution("AAPL", "mentions")
|
|
608
|
-
client.entityMetrics.getDistribution("AAPL", "mentions", { dimension: "source" })
|
|
609
|
-
|
|
610
|
-
// Mean sentiment by source, in [-1, 1] (valueType "MEAN")
|
|
611
|
-
client.entityMetrics.getDistribution("AAPL", "sentiment")
|
|
612
|
-
```
|
|
613
|
-
|
|
614
|
-
In a distribution, `valueType` says what each number is. For a count metric such as `mentions` or `creators` it is `"SHARE_PERCENT"`: each value is that source's percentage share of the total, summing to about 100. For `sentiment` it is `"MEAN"`: each value is that source's mean polarity over the window, in [-1, 1], the same numbers as `GET /api/v2/metrics/entity/{symbol}/metric/sentiment/mean-by/source` in the [API reference](https://sentisense.ai/docs/api/metrics/). `sentisense_score` has no per-source split and answers with an empty distribution.
|
|
615
|
-
|
|
616
|
-
Available metric types: `mentions`, `sentiment`, `sentisense_score`, `sentisense_rating`, `social_dominance`, `creators`, `app_review_count`, `app_rating`, `app_all_ratings_count`, `app_all_ratings_avg`. `sentisense` is an alias for `sentisense_score`; either spelling returns the same series, and keys are case-insensitive. Responses always name the canonical type, so a `sentisense` request answers with `SENTISENSE_SCORE`. `sentisense_rating` is the SentiSense Rating score and is a time series only: it has no source breakdown, so `getDistribution` answers with an empty distribution for it.
|
|
617
|
-
|
|
618
|
-
The four `app_` metrics are daily Apple App Store series for product entities that have an app, so pass an entity slug such as `"Instagram"` rather than a ticker. `app_review_count` and `app_rating` cover the written reviews published that day, a small share of all ratings whose stars skew lower; `app_all_ratings_count` and `app_all_ratings_avg` cover every new rating, star-only and written together, and have no point on a day with no net new ratings or when the store's totals fell. Over a range, weight each day's `app_all_ratings_avg` by `app_all_ratings_count` for the period average. Each point's flat `value` is the count or the average stars.
|
|
619
|
-
|
|
620
|
-
### Options
|
|
621
|
-
|
|
622
|
-
End-of-day options positioning: where implied volatility, put/call flow and skew are unusual today, and how a name's readings have trended.
|
|
623
|
-
|
|
624
|
-
```typescript
|
|
625
|
-
client.options.getOverview() // Market-wide radar, ranked
|
|
626
|
-
client.stocks.getOptionsSummary("NVDA") // One name's full dossier
|
|
627
|
-
client.stocks.getOptionsHistory("NVDA", { window: "2y" }) // That name's daily series
|
|
628
|
-
client.stocks.getOptionsIntradayHistory("NVDA", { session: "2026-10-14" }) // Every 15-minute cycle of one session (PRO)
|
|
629
|
-
```
|
|
630
|
-
|
|
631
|
-
The radar carries two separately-ranked boards: `data.rows` for stocks and `data.etfRows` for ETFs. Keep them apart. Every reading behind a row's `interestScore` is a percentile of that ticker's own trailing history, so a ranking built across both boards compares numbers measured against different baselines. The aggregates split the same way, with the `etf`-prefixed fields describing the ETF board alone.
|
|
632
|
-
|
|
633
|
-
During the trading session the dossier and the radar also carry a few intraday fields, the same on every tier: `intradayFlow` (a count of the ticker's unusual contracts so far, when the first one was flagged, and the board's own clock), `largePrintCount` and `largestPrintPctl` on the dossier, and `intradayActiveCount` with `intradayRanking` on the radar. They carry no contract, strike, price or premium, and are absent before the day's first board. On the radar, `intradayAsOf` (epoch seconds) and `intradayAsOfEt` date the board the ranking was read from. `capabilities.intradayBoard` says where the contract-level board lives; its rows are served in the SentiSense app, not by the API.
|
|
634
|
-
|
|
635
|
-
`getOptionsIntradayHistory` keeps every cycle of that board for one ticker, so you can test an intraday signal against what the board showed at each point in the day and then compare it with the session's end-of-day row from `getOptionsHistory`:
|
|
636
|
-
|
|
637
|
-
```typescript
|
|
638
|
-
const day = await client.stocks.getOptionsIntradayHistory("NVDA", { session: "2026-10-14" });
|
|
639
|
-
if (day.data === null) {
|
|
640
|
-
console.log(day.upgrade?.message); // PRO only: a FREE key gets a preview with no series
|
|
641
|
-
} else {
|
|
642
|
-
for (const point of day.data.series) { // oldest cycle first
|
|
643
|
-
console.log(point.asOfEt, point.callVol, point.putVol, point.pcVol, point.unusualCount, point.atmIv);
|
|
644
|
-
}
|
|
645
|
-
}
|
|
646
|
-
```
|
|
647
|
-
|
|
648
|
-
Each point carries call and put volume so far, the put/call ratio, the unusual-contract count, the percentile of the largest qualifying contract against the ticker's own year (`maxPremiumPctl1y`) and the ATM implied volatility; readings that are unavailable are absent, never zero. Omit `session` for the session the board ran most recently, and read `data.session` for the date served. A ticker appears only on cycles where it was on the board, so gaps show in each point's `cycle`, and `missingCycles` lists cycles whose stored point could not be read. A weekend, a holiday, a ticker outside the board and an unknown symbol all return an empty `series`, not a null payload. A malformed or future date rejects with an `APIError` whose `code` is `"invalid_session"`. From the CLI: `sentisense options NVDA --intraday`, or `--session YYYY-MM-DD` for another day.
|
|
649
|
-
|
|
650
|
-
A FREE key that has spent its ten monthly dossiers receives a headline preview from `getOptionsSummary`: `asOf`, `sentiment` and six flat readings, `ivRank1y`, `atmIv`, `expectedMove1d`, `pcVol`, `pcVolPctl1y` and `maxPain`, with no `latest`, `context` or `oiWalls`. On a full dossier those six are absent and the same readings live in the nested objects, so branch on `isPreview`.
|
|
651
|
-
|
|
652
|
-
A row whose baseline is still building carries its raw readings with the percentiles and `interestScore` omitted, which means "not enough history yet" rather than "nothing interesting". `getOptionsSummary` reports an uncovered ticker as a null payload inside the usual envelope, so the check is `result.data === null`: the response object itself is always truthy, and a bare `if (summary === null)` never fires. `getOptionsHistory` reports it as an empty `series` instead, so check the array's length rather than null-checking there.
|
|
653
|
-
|
|
654
|
-
On a delisted symbol, the options summary carries `listingStatus === "DELISTED"` and, when known, `delistedDate` (YYYY-MM-DD). This marks a frozen last dossier, so read `asOf` before treating it as current. Listed and pending symbols omit both fields.
|
|
345
|
+
Free keys get the full series for the [sample companies](https://sentisense.ai/docs/api/#full-sample-responses-with-a-free-key), such as TSLA, and a preview for the rest.
|
|
655
346
|
|
|
656
|
-
###
|
|
657
|
-
|
|
658
|
-
Where a stock ranks against the other stocks rated that day, as a score, a letter and a percentile, plus the seven dimensions the rank is blended from. It is a relative research signal for informational and educational purposes, not financial, investment or trading advice, and not a recommendation about any security. Every response carries the wording to display alongside a grade in `disclaimer`. [Methodology](https://sentisense.ai/methodology/#sentisense-rating).
|
|
659
|
-
|
|
660
|
-
```typescript
|
|
661
|
-
const rating = await client.stocks.getRating("AAPL");
|
|
662
|
-
if (rating.rated) {
|
|
663
|
-
console.log(rating.letter, rating.score, "percentile", rating.percentile, "of", rating.ratedCount);
|
|
664
|
-
for (const adj of rating.riskAdjustments ?? []) console.log(" ", adj.condition, -adj.points);
|
|
665
|
-
for (const dim of rating.dimensions.filter((d) => d.present)) {
|
|
666
|
-
console.log(" ", dim.label, dim.percentile);
|
|
667
|
-
}
|
|
668
|
-
} else {
|
|
669
|
-
console.log("no grade today:", rating.reason);
|
|
670
|
-
}
|
|
671
|
-
```
|
|
672
|
-
|
|
673
|
-
`getRating` returns `StockRatingResponse`, a discriminated union on `rated` of `StockRating` (graded) and `StockNotRated`. The `if` narrows to `score`, `letter`, `percentile`, `composite`, `ratedCount` and `methodologyVersion`, the `else` to `reason`, `dimensionsPresent` and `presentDimensions`. Branch on that flag rather than testing a field for `undefined`.
|
|
674
|
-
|
|
675
|
-
Having no grade is a normal 200, not a 404: ETFs and tickers outside the swept universe answer that way, and `reason` is one of `stale`, `not_rated_today`, `insufficient_dimensions` or `insufficient_coverage_weight`. Only a ticker that resolves to nothing we track rejects with `NotFoundError`.
|
|
676
|
-
|
|
677
|
-
`dimensions` always holds all seven rows in a fixed order, including the ones with no data, which arrive with `present` false and a `null` percentile. Read `present` first and never substitute zero for a missing percentile: zero is the bottom of the cross-section, absence is not a position on it. Only the smart-money dimension carries `subLegs`.
|
|
678
|
-
|
|
679
|
-
**`score` is not `percentile`.** `percentile` is the rank of the blended signals against the day's rated set. `score = percentile - sum(riskAdjustments.map((a) => a.points))`, floored at 10 when fewer than five dimensions are available, and it is the number `letter` bands (A 90, B 70, C 30, D 10). `bucketLetter` is the band the percentile alone would give, so the two letters differ by exactly what the conditions cost. `riskAdjustments` itemises that cost, `penaltyPoints` totals it, and `riskConditions` names the active ones from the `RiskCondition` union: `thin_coverage`, `weak_dimension`, `unprofitable`, `no_fundamentals`, `high_leverage`, `unseasoned_listing`, `small_market_cap`, `thin_liquidity`, `extended_price`, `insider_selling` and `institutional_outflow`.
|
|
680
|
-
|
|
681
|
-
All five are optional: a response served before they shipped omits them. For the daily history of a stock's score, ask `entityMetrics.getMetrics` for the `sentisense_rating` metric.
|
|
682
|
-
|
|
683
|
-
### Market mood & knowledge base
|
|
684
|
-
|
|
685
|
-
```typescript
|
|
686
|
-
client.marketMood.get() // Composite market sentiment with sub-signals
|
|
687
|
-
client.marketMood.get({ days: 30 }) // Same, with 30 days of history (default 180)
|
|
688
|
-
client.kb.getPopularEntities() // Most-tracked entities
|
|
689
|
-
client.kb.searchEntities("Tesla") // Resolve a name, alias, ticker or slug to what we track
|
|
690
|
-
```
|
|
691
|
-
|
|
692
|
-
Entity search is resolution, not enumeration: the query must be at least 2 characters, the match count is capped at 25, and it returns a bare `EntitySearchResult[]` rather than a `PreviewResponse` envelope. Each hit carries `name`, `type`, the `ticker` for a listed entity (`null` for everything else), and the `urlSlug` the metric endpoints address that entity by, which is the only way to get a handle for a person, product or topic with no ticker.
|
|
693
|
-
|
|
694
|
-
```typescript
|
|
695
|
-
const hits = await client.kb.searchEntities("Tesla", { type: "company", limit: 5 });
|
|
696
|
-
const symbol = hits.find((hit) => hit.ticker)?.ticker; // "TSLA"
|
|
697
|
-
```
|
|
698
|
-
|
|
699
|
-
An empty array is the normal answer for a query that matches nothing, so branch on `length` rather than catching.
|
|
700
|
-
|
|
701
|
-
### Trackers
|
|
702
|
-
|
|
703
|
-
Every tracker returns the same snapshot envelope, so one renderer per `viewType` covers them all. `trackers.list()` says which trackers exist and, on those that have them, the `filters` each accepts (`{ key, values }`, with `values` the complete list).
|
|
347
|
+
### ETFs (beta)
|
|
704
348
|
|
|
705
349
|
```typescript
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
//
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
for (const row of tx.data.rows ?? []) {
|
|
713
|
-
console.log(row.rowId, row.name, row.ticker, row.endsDate, row.statesNamed);
|
|
714
|
-
}
|
|
350
|
+
client.etfs.list() // every ETF we track
|
|
351
|
+
client.etfs.quote("SPY") // a fund's quote with AUM, expense ratio and NAV
|
|
352
|
+
client.etfs.holdings("QQQ") // what the fund holds, with weights
|
|
353
|
+
client.etfs.analystAggregate("QQQ") // analyst consensus across the holdings, by weight
|
|
354
|
+
client.etfs.insiderAggregate("ARKK", { lookbackDays: 90 }) // insider buying and selling across the holdings
|
|
355
|
+
client.etfs.sentimentAggregate("QQQ") // the fund's Score, from holdings and from talk about the fund
|
|
715
356
|
```
|
|
716
357
|
|
|
717
|
-
|
|
358
|
+
[ETF API docs](https://sentisense.ai/docs/api/etfs/)
|
|
718
359
|
|
|
719
360
|
### Screener
|
|
720
361
|
|
|
721
|
-
Filter the tracked universe on the SentiSense Score, attention, analyst consensus, technicals, price and end-of-day options readings in one query. Screening on analyst ratings alone is something a dozen free tools do; screening on analyst ratings *where the Score disagrees* is not.
|
|
722
|
-
|
|
723
362
|
```typescript
|
|
724
|
-
client.screener.fields()
|
|
725
|
-
client.screener.screens()
|
|
726
|
-
client.screener.run({ plan, tickers, limit })
|
|
727
|
-
client.screener.runEtfs({ plan, limit })
|
|
363
|
+
client.screener.fields() // every field you can filter on
|
|
364
|
+
client.screener.screens() // our ready-made screens
|
|
365
|
+
client.screener.run({ plan, tickers, limit }) // run a screen over stocks
|
|
366
|
+
client.screener.runEtfs({ plan, limit }) // run a screen over ETFs
|
|
728
367
|
```
|
|
729
368
|
|
|
730
369
|
```typescript
|
|
731
|
-
//
|
|
732
|
-
const { screens } = await client.screener.screens();
|
|
733
|
-
const crowdVsStreet = screens.find((s) => s.id === "crowd-vs-street")!;
|
|
734
|
-
const curated = await client.screener.run({ plan: crowdVsStreet.plan, limit: 25 });
|
|
735
|
-
console.log(`${curated.matched} matched, showing ${curated.results.length}`);
|
|
736
|
-
|
|
737
|
-
// Or build your own: bullish Score, thin analyst enthusiasm
|
|
370
|
+
// High 7-day Score, few analyst buy ratings
|
|
738
371
|
const res = await client.screener.run({
|
|
739
372
|
plan: {
|
|
740
373
|
filters: [
|
|
741
374
|
{ fieldName: "SENTI_SCORE_7D", op: "GTE", value: 13 },
|
|
742
375
|
{ fieldName: "ANALYST_BUY_RATIO_PCT", op: "LTE", value: 30 },
|
|
743
|
-
{ fieldName: "ANALYST_COUNT", op: "GTE", value: 5 },
|
|
744
376
|
],
|
|
745
377
|
sort: { fieldName: "SENTI_SCORE_7D", dir: "DESC" },
|
|
746
378
|
},
|
|
747
379
|
limit: 25,
|
|
748
380
|
});
|
|
749
|
-
for (const row of res.results)
|
|
750
|
-
console.log(row.ticker, row.sentiSenseScore7D, row.analystBuyRatioPct);
|
|
751
|
-
}
|
|
752
|
-
|
|
753
|
-
// Options positioning: implied volatility in the top quarter of its own year
|
|
754
|
-
const highIv = await client.screener.run({
|
|
755
|
-
plan: {
|
|
756
|
-
filters: [{ fieldName: "IV_RANK_1Y", op: "GTE", value: 75 }],
|
|
757
|
-
sort: { fieldName: "IV_RANK_1Y", dir: "DESC" },
|
|
758
|
-
},
|
|
759
|
-
limit: 25,
|
|
760
|
-
});
|
|
761
|
-
for (const row of highIv.results) {
|
|
762
|
-
console.log(row.ticker, row.ivRank1y, row.expectedMove20d, row.optionsAsOf);
|
|
763
|
-
}
|
|
381
|
+
for (const row of res.results) console.log(row.ticker, row.sentiSenseScore7D, row.analystBuyRatioPct);
|
|
764
382
|
```
|
|
765
383
|
|
|
766
|
-
`
|
|
384
|
+
`ANALYST_RATING_MEAN` runs backwards (1 is strong buy), so prefer `ANALYST_BUY_RATIO_PCT`. [Screener API docs](https://sentisense.ai/docs/api/screener/)
|
|
767
385
|
|
|
768
|
-
|
|
386
|
+
### Market mood
|
|
769
387
|
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
|
|
388
|
+
```typescript
|
|
389
|
+
client.marketMood.get({ days: 30 }) // Market Mood, from fear to greed, with its history
|
|
390
|
+
client.indexes.list() // our indexes
|
|
391
|
+
client.indexes.history("ai-sentiment") // one index over time
|
|
392
|
+
```
|
|
773
393
|
|
|
774
|
-
|
|
394
|
+
[Market Mood API docs](https://sentisense.ai/docs/api/market-mood/)
|
|
775
395
|
|
|
776
|
-
|
|
396
|
+
### Trackers
|
|
777
397
|
|
|
778
|
-
|
|
398
|
+
```typescript
|
|
399
|
+
const { trackers } = await client.trackers.list();
|
|
400
|
+
const tx = await client.trackers.get("data-center-moratoriums", { filter: { state: "TX" } });
|
|
401
|
+
for (const row of tx.data.rows ?? []) console.log(row.rowId, row.name);
|
|
402
|
+
```
|
|
403
|
+
|
|
404
|
+
Every tracker uses the same envelope, so render by its `viewType`. Columns we don't type yet are still on each row. [Trackers API docs](https://sentisense.ai/docs/api/trackers/)
|
|
779
405
|
|
|
780
|
-
|
|
406
|
+
### Knowledge base
|
|
407
|
+
|
|
408
|
+
```typescript
|
|
409
|
+
client.kb.getPopularEntities() // the most-followed people, products and companies
|
|
410
|
+
client.kb.searchEntities("Tesla", { type: "company", limit: 5 }) // turn a name into a ticker and slug
|
|
411
|
+
```
|
|
781
412
|
|
|
782
|
-
|
|
413
|
+
`searchEntities` returns a plain array, empty when nothing matches. [Entities API docs](https://sentisense.ai/docs/api/entities/)
|
|
783
414
|
|
|
784
415
|
## Error handling
|
|
785
416
|
|
|
786
417
|
```typescript
|
|
787
|
-
import SentiSense, {
|
|
418
|
+
import SentiSense, { NotFoundError, RateLimitError } from "sentisense";
|
|
788
419
|
|
|
789
420
|
try {
|
|
790
|
-
const
|
|
421
|
+
const price = await client.stocks.getPrice("AAPL");
|
|
791
422
|
} catch (error) {
|
|
792
|
-
if (error instanceof
|
|
793
|
-
|
|
794
|
-
} else if (error instanceof RateLimitError) {
|
|
795
|
-
if (error.code === "quota_exceeded") {
|
|
796
|
-
// 429: monthly allowance used up. Not retried; error.message says when it resets.
|
|
797
|
-
} else {
|
|
798
|
-
// 429: per-minute limit ("rate_limit_exceeded"), thrown once retries are used up.
|
|
799
|
-
// error.retryAfter is the server's wait in seconds.
|
|
800
|
-
}
|
|
801
|
-
}
|
|
423
|
+
if (error instanceof NotFoundError) console.log("Not covered:", error.code);
|
|
424
|
+
else if (error instanceof RateLimitError) console.log(error.message);
|
|
802
425
|
}
|
|
803
426
|
```
|
|
804
427
|
|
|
805
428
|
| Error class | HTTP status | When |
|
|
806
|
-
|
|
807
|
-
| `AuthenticationError` | 401, 403 |
|
|
808
|
-
| `NotFoundError` | 404 |
|
|
809
|
-
| `RateLimitError` | 429 |
|
|
810
|
-
| `
|
|
429
|
+
|-------------|-------------|------|
|
|
430
|
+
| `AuthenticationError` | 401, 403 | The key is missing or wrong |
|
|
431
|
+
| `NotFoundError` | 404 | We don't track that symbol, or hold nothing of that kind for it |
|
|
432
|
+
| `RateLimitError` | 429 | The per-minute limit (`retryAfter`) or the monthly allowance (`code: "quota_exceeded"`) |
|
|
433
|
+
| `DeepHistoryUnavailableError` | 202 | A `10Y` or `MAX` chart is still being built. Try again shortly |
|
|
434
|
+
| `TemporarilyUnavailableError` | 503 | The server asked for a longer wait than the client allows |
|
|
435
|
+
| `APIError` | other | Anything else |
|
|
811
436
|
|
|
812
|
-
All
|
|
437
|
+
All of them extend `SentiSenseError` and carry `status`, `code`, `message` and `body`, the parsed error response: a 404's `suggestions` and `coverage` block, a free key's 429 `upgrade` block. The client already retried what it could before throwing.
|
|
813
438
|
|
|
814
439
|
## Links
|
|
815
440
|
|
|
816
|
-
-
|
|
817
|
-
-
|
|
441
|
+
- API docs: [sentisense.ai/docs/api](https://sentisense.ai/docs/api/)
|
|
442
|
+
- Help with keys, limits and previews: [sentisense.ai/docs/support](https://sentisense.ai/docs/support/)
|
|
818
443
|
- Changelog: [CHANGELOG.md](./CHANGELOG.md)
|
|
819
444
|
|
|
820
445
|
SentiSense provides research data for informational and educational purposes, not investment advice.
|