sentisense 0.76.0 → 0.78.0
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 +231 -594
- package/dist/cli.cjs +173 -46
- package/dist/index.cjs +64 -31
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.mts +247 -10
- package/dist/index.d.ts +247 -10
- package/dist/index.mjs +64 -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
|
|
55
|
+
|
|
56
|
+
Try the API without writing code:
|
|
56
57
|
|
|
57
58
|
```bash
|
|
58
|
-
export SENTISENSE_API_KEY=<your key>
|
|
59
|
-
|
|
60
|
-
npx -y sentisense@latest
|
|
61
|
-
|
|
62
|
-
npx -y sentisense@latest health
|
|
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 |
|
|
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) |
|
|
183
118
|
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
Keep the key in the environment rather than in source. Committing a literal key leaks it into git history and into every registry security scan that reads your repo.
|
|
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
|
|
191
|
-
|
|
192
|
-
**1. Tier-gated endpoints return a preview envelope.** The payload is in `data`, and `isPreview` tells you whether it was truncated for your tier. `totalCount` carries the untruncated size whenever the server knows it: on a truncated response, so you can render "showing N of M", and on a paged endpoint such as `politicians.getActivity`, where it is the full match count on every tier including PRO. A missing `totalCount` means "count `data` yourself", never "zero results".
|
|
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.
|
|
193
124
|
|
|
194
|
-
|
|
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,603 +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
|
-
|
|
233
|
-
|
|
234
|
-
Affected: `documents.getByTicker` / `getByTickerRange` / `getByEntity` / `search` / `getBySource`. Also `stocks.getFundamentalsPeriods`, whose periods are in `periods`.
|
|
235
|
-
|
|
236
|
-
```typescript
|
|
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
|
-
```
|
|
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.
|
|
243
147
|
|
|
244
|
-
|
|
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`.
|
|
245
149
|
|
|
246
|
-
|
|
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:
|
|
356
|
-
|
|
357
|
-
```typescript
|
|
358
|
-
import type { InstitutionDetail, PreviewResponse } from "sentisense";
|
|
235
|
+
[Insights API docs](https://sentisense.ai/docs/api/insights/)
|
|
359
236
|
|
|
360
|
-
|
|
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
|
-
|
|
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/)
|
|
393
246
|
|
|
394
|
-
|
|
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`. |
|
|
400
|
-
|
|
401
|
-
`limit` is the switch for the whole set: send `offset`, `sortBy`, or `sortDir` without it and the server ignores them, returning the full unsorted list with a 200 and no warning.
|
|
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
|
-
```
|
|
453
|
-
|
|
454
|
-
### Insider trading (Form 4)
|
|
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
273
|
```
|
|
461
274
|
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
### Analyst ratings
|
|
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.
|
|
467
|
-
|
|
468
|
-
```typescript
|
|
469
|
-
client.analyst.consensus("AAPL") // Price target cone + consensus. Free, full data.
|
|
470
|
-
client.analyst.consensusHistory("AAPL", { limit: 90 }) // Daily history. Free: last 30 days; distribution fields null.
|
|
471
|
-
client.analyst.calledIt("AAPL", { limit: 10 }) // Recorded calls for 20% moves over five sessions. Free: newest move, up to 5 calls, move counts intact.
|
|
472
|
-
client.analyst.actions("AAPL", { lookbackDays: 30 }) // Upgrade/downgrade feed. Free: 3 most recent.
|
|
473
|
-
client.analyst.estimates("AAPL") // Forward EPS + surprises. Free: 1 quarter. data.ticker: the listing per-share figures are for (BRK-A answers BRK.B).
|
|
474
|
-
client.analyst.marketActivity({ lookbackDays: 7 }) // Market-wide analyst actions (PRO).
|
|
475
|
-
```
|
|
275
|
+
[Politicians API docs](https://sentisense.ai/docs/api/politicians/)
|
|
476
276
|
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
```typescript
|
|
480
|
-
client.analyst.coverage("NVDA", { lookbackDays: 365 }) // Who covers it, by firm. Free: 5 firms.
|
|
481
|
-
client.analyst.profile("gil-luria") // One analyst's firms + coverage book.
|
|
482
|
-
client.analyst.calls("gil-luria", { limit: 25 }) // Their price target notes, newest first.
|
|
483
|
-
```
|
|
277
|
+
### Institutional flows (13F)
|
|
484
278
|
|
|
485
279
|
```typescript
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
}
|
|
495
|
-
|
|
496
|
-
for (const row of book.coverage.slice(0, 5)) {
|
|
497
|
-
if (row.noteCount === 0) {
|
|
498
|
-
// A desk can cover a stock on rating actions alone, with no price target.
|
|
499
|
-
console.log(`${row.firm}: rating only, ${row.firmRating?.rating}`);
|
|
500
|
-
continue;
|
|
501
|
-
}
|
|
502
|
-
const who = row.latestNote?.analyst ?? "unattributed";
|
|
503
|
-
console.log(`${row.firm}: ${row.latestNote?.priceTarget} (${who})`);
|
|
504
|
-
|
|
505
|
-
for (const analyst of row.analysts) {
|
|
506
|
-
if (!analyst.slug) continue;
|
|
507
|
-
const calls = await client.analyst.calls(analyst.slug, { limit: 10 });
|
|
508
|
-
console.log(` ${analyst.name}: ${calls.totalCount} notes on record`);
|
|
509
|
-
}
|
|
510
|
-
}
|
|
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
|
|
511
288
|
```
|
|
512
289
|
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
`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.
|
|
516
|
-
|
|
517
|
-
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%).
|
|
518
|
-
|
|
519
|
-
### Earnings
|
|
520
|
-
|
|
521
|
-
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.
|
|
522
|
-
|
|
523
|
-
```typescript
|
|
524
|
-
client.earnings.getSummaries("AAPL", { limit: 4 }) // Per-quarter analysis, newest first. Free: latest quarter, shaped.
|
|
525
|
-
client.earnings.getRecent({ days: 7, limit: 25 }) // Who reported in the last N days. Full window on every key.
|
|
526
|
-
client.earnings.getReactions("AAPL") // Up to twelve measured post-report moves. Full series on every key.
|
|
527
|
-
client.earnings.getStatistics({ window: "week_to_date" }) // Market-wide outcomes, reaction rates, baseline, and coverage.
|
|
528
|
-
client.earnings.getRanked({ reportedDays: 14, upcomingDays: 7 }) // Free: first 3 rows per section. PRO: full ranking.
|
|
529
|
-
```
|
|
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`.
|
|
530
292
|
|
|
531
293
|
```typescript
|
|
532
|
-
const
|
|
533
|
-
const quarter = res.data[0];
|
|
534
|
-
|
|
294
|
+
const quarter = (await client.institutional.getQuarters()).find((q) => !q.pending)?.reportDate;
|
|
535
295
|
if (quarter) {
|
|
536
|
-
|
|
537
|
-
console.log(
|
|
538
|
-
for (const kpi of quarter.kpiHighlights ?? []) {
|
|
539
|
-
console.log(` ${kpi.label}: ${kpi.value} (${kpi.yoy ?? "no YoY"})`);
|
|
540
|
-
}
|
|
541
|
-
|
|
542
|
-
if (res.isPreview) {
|
|
543
|
-
// Free key: section titles stand in for the bodies.
|
|
544
|
-
console.log("Summary covers:", quarter.summaryTopics?.join(", "));
|
|
545
|
-
} else {
|
|
546
|
-
console.log(quarter.summaryMd);
|
|
547
|
-
}
|
|
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);
|
|
548
298
|
}
|
|
549
299
|
```
|
|
550
300
|
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
`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`.
|
|
554
|
-
|
|
555
|
-
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.
|
|
556
|
-
|
|
557
|
-
### Company KPIs (PRO)
|
|
558
|
-
|
|
559
|
-
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).
|
|
560
|
-
|
|
561
|
-
```typescript
|
|
562
|
-
client.stocks.getKpis("TSLA") // Product metrics and segment revenue. Free: full series for the sample companies, metadata only for the rest. PRO: full series.
|
|
563
|
-
client.stocks.listKpiCoverage() // All tickers with curated KPI data (free, no quota cost)
|
|
564
|
-
```
|
|
565
|
-
|
|
566
|
-
### ETFs (beta)
|
|
567
|
-
|
|
568
|
-
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.
|
|
569
|
-
|
|
570
|
-
```typescript
|
|
571
|
-
client.etfs.list() // Every ETF tracked
|
|
572
|
-
client.etfs.quote("SPY") // Price, ranges, AUM, expense ratio, NAV
|
|
573
|
-
client.etfs.holdings("QQQ") // Full composition + freshness metadata
|
|
574
|
-
client.etfs.analystAggregate("QQQ") // Holdings-weighted analyst consensus
|
|
575
|
-
client.etfs.insiderAggregate("ARKK", { lookbackDays: 90 }) // Holdings-weighted Form 4 net flow
|
|
576
|
-
client.etfs.sentimentAggregate("QQQ") // Constituent-weighted vs direct Score
|
|
577
|
-
```
|
|
578
|
-
|
|
579
|
-
### Entity metrics
|
|
580
|
-
|
|
581
|
-
```typescript
|
|
582
|
-
// Time-series metrics (v2 API)
|
|
583
|
-
client.entityMetrics.getMetrics("AAPL", { metricType: "sentiment" })
|
|
584
|
-
client.entityMetrics.getMetrics("AAPL", {
|
|
585
|
-
metricType: "mentions",
|
|
586
|
-
startTime: Date.now() - 7 * 86400000,
|
|
587
|
-
endTime: Date.now(),
|
|
588
|
-
maxDataPoints: 100,
|
|
589
|
-
})
|
|
590
|
-
|
|
591
|
-
// Daily App Store ratings for a product entity with an app (an entity slug, not a ticker)
|
|
592
|
-
client.entityMetrics.getMetrics("Instagram", { metricType: "app_all_ratings_count" })
|
|
593
|
-
|
|
594
|
-
// Share of mentions by source (valueType "SHARE_PERCENT")
|
|
595
|
-
client.entityMetrics.getDistribution("AAPL", "mentions")
|
|
596
|
-
client.entityMetrics.getDistribution("AAPL", "mentions", { dimension: "source" })
|
|
597
|
-
|
|
598
|
-
// Mean sentiment by source, in [-1, 1] (valueType "MEAN")
|
|
599
|
-
client.entityMetrics.getDistribution("AAPL", "sentiment")
|
|
600
|
-
```
|
|
301
|
+
[13F API docs](https://sentisense.ai/docs/api/institutional-flows/)
|
|
601
302
|
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
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.
|
|
605
|
-
|
|
606
|
-
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.
|
|
607
|
-
|
|
608
|
-
### Options
|
|
609
|
-
|
|
610
|
-
End-of-day options positioning: where implied volatility, put/call flow and skew are unusual today, and how a name's readings have trended.
|
|
303
|
+
### Analyst ratings
|
|
611
304
|
|
|
612
305
|
```typescript
|
|
613
|
-
client.
|
|
614
|
-
client.
|
|
615
|
-
client.
|
|
616
|
-
client.
|
|
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
|
|
617
315
|
```
|
|
618
316
|
|
|
619
|
-
|
|
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/)
|
|
620
318
|
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
`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`:
|
|
319
|
+
### Earnings
|
|
624
320
|
|
|
625
321
|
```typescript
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
}
|
|
633
|
-
}
|
|
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
|
|
634
328
|
```
|
|
635
329
|
|
|
636
|
-
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.
|
|
637
|
-
|
|
638
|
-
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`.
|
|
639
|
-
|
|
640
|
-
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.
|
|
641
|
-
|
|
642
|
-
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.
|
|
643
|
-
|
|
644
|
-
### SentiSense Rating
|
|
645
|
-
|
|
646
|
-
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).
|
|
647
|
-
|
|
648
330
|
```typescript
|
|
649
|
-
const
|
|
650
|
-
if (
|
|
651
|
-
console.log(rating.letter, rating.score, "percentile", rating.percentile, "of", rating.ratedCount);
|
|
652
|
-
for (const adj of rating.riskAdjustments ?? []) console.log(" ", adj.condition, -adj.points);
|
|
653
|
-
for (const dim of rating.dimensions.filter((d) => d.present)) {
|
|
654
|
-
console.log(" ", dim.label, dim.percentile);
|
|
655
|
-
}
|
|
656
|
-
} else {
|
|
657
|
-
console.log("no grade today:", rating.reason);
|
|
658
|
-
}
|
|
331
|
+
const [quarter] = (await client.earnings.getSummaries("AAPL", { limit: 1 })).data;
|
|
332
|
+
if (quarter) console.log(quarter.fiscalPeriod, quarter.headline);
|
|
659
333
|
```
|
|
660
334
|
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
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`.
|
|
664
|
-
|
|
665
|
-
`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`.
|
|
666
|
-
|
|
667
|
-
**`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`.
|
|
668
|
-
|
|
669
|
-
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.
|
|
335
|
+
[Earnings API docs](https://sentisense.ai/docs/api/earnings/)
|
|
670
336
|
|
|
671
|
-
###
|
|
672
|
-
|
|
673
|
-
```typescript
|
|
674
|
-
client.marketMood.get() // Composite market sentiment with sub-signals
|
|
675
|
-
client.marketMood.get({ days: 30 }) // Same, with 30 days of history (default 180)
|
|
676
|
-
client.kb.getPopularEntities() // Most-tracked entities
|
|
677
|
-
client.kb.searchEntities("Tesla") // Resolve a name, alias, ticker or slug to what we track
|
|
678
|
-
```
|
|
679
|
-
|
|
680
|
-
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.
|
|
337
|
+
### Company KPIs (PRO)
|
|
681
338
|
|
|
682
339
|
```typescript
|
|
683
|
-
|
|
684
|
-
|
|
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
|
|
685
343
|
```
|
|
686
344
|
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
### Trackers
|
|
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.
|
|
690
346
|
|
|
691
|
-
|
|
347
|
+
### ETFs (beta)
|
|
692
348
|
|
|
693
349
|
```typescript
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
|
|
697
|
-
//
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
for (const row of tx.data.rows ?? []) {
|
|
701
|
-
console.log(row.rowId, row.name, row.ticker, row.endsDate, row.statesNamed);
|
|
702
|
-
}
|
|
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
|
|
703
356
|
```
|
|
704
357
|
|
|
705
|
-
|
|
358
|
+
[ETF API docs](https://sentisense.ai/docs/api/etfs/)
|
|
706
359
|
|
|
707
360
|
### Screener
|
|
708
361
|
|
|
709
|
-
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.
|
|
710
|
-
|
|
711
362
|
```typescript
|
|
712
|
-
client.screener.fields()
|
|
713
|
-
client.screener.screens()
|
|
714
|
-
client.screener.run({ plan, tickers, limit })
|
|
715
|
-
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
|
|
716
367
|
```
|
|
717
368
|
|
|
718
369
|
```typescript
|
|
719
|
-
//
|
|
720
|
-
const { screens } = await client.screener.screens();
|
|
721
|
-
const crowdVsStreet = screens.find((s) => s.id === "crowd-vs-street")!;
|
|
722
|
-
const curated = await client.screener.run({ plan: crowdVsStreet.plan, limit: 25 });
|
|
723
|
-
console.log(`${curated.matched} matched, showing ${curated.results.length}`);
|
|
724
|
-
|
|
725
|
-
// Or build your own: bullish Score, thin analyst enthusiasm
|
|
370
|
+
// High 7-day Score, few analyst buy ratings
|
|
726
371
|
const res = await client.screener.run({
|
|
727
372
|
plan: {
|
|
728
373
|
filters: [
|
|
729
374
|
{ fieldName: "SENTI_SCORE_7D", op: "GTE", value: 13 },
|
|
730
375
|
{ fieldName: "ANALYST_BUY_RATIO_PCT", op: "LTE", value: 30 },
|
|
731
|
-
{ fieldName: "ANALYST_COUNT", op: "GTE", value: 5 },
|
|
732
376
|
],
|
|
733
377
|
sort: { fieldName: "SENTI_SCORE_7D", dir: "DESC" },
|
|
734
378
|
},
|
|
735
379
|
limit: 25,
|
|
736
380
|
});
|
|
737
|
-
for (const row of res.results)
|
|
738
|
-
console.log(row.ticker, row.sentiSenseScore7D, row.analystBuyRatioPct);
|
|
739
|
-
}
|
|
740
|
-
|
|
741
|
-
// Options positioning: implied volatility in the top quarter of its own year
|
|
742
|
-
const highIv = await client.screener.run({
|
|
743
|
-
plan: {
|
|
744
|
-
filters: [{ fieldName: "IV_RANK_1Y", op: "GTE", value: 75 }],
|
|
745
|
-
sort: { fieldName: "IV_RANK_1Y", dir: "DESC" },
|
|
746
|
-
},
|
|
747
|
-
limit: 25,
|
|
748
|
-
});
|
|
749
|
-
for (const row of highIv.results) {
|
|
750
|
-
console.log(row.ticker, row.ivRank1y, row.expectedMove20d, row.optionsAsOf);
|
|
751
|
-
}
|
|
381
|
+
for (const row of res.results) console.log(row.ticker, row.sentiSenseScore7D, row.analystBuyRatioPct);
|
|
752
382
|
```
|
|
753
383
|
|
|
754
|
-
`
|
|
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/)
|
|
755
385
|
|
|
756
|
-
|
|
386
|
+
### Market mood
|
|
757
387
|
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
|
|
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
|
+
```
|
|
761
393
|
|
|
762
|
-
|
|
394
|
+
[Market Mood API docs](https://sentisense.ai/docs/api/market-mood/)
|
|
763
395
|
|
|
764
|
-
|
|
396
|
+
### Trackers
|
|
765
397
|
|
|
766
|
-
|
|
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/)
|
|
767
405
|
|
|
768
|
-
|
|
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
|
+
```
|
|
769
412
|
|
|
770
|
-
|
|
413
|
+
`searchEntities` returns a plain array, empty when nothing matches. [Entities API docs](https://sentisense.ai/docs/api/entities/)
|
|
771
414
|
|
|
772
415
|
## Error handling
|
|
773
416
|
|
|
774
417
|
```typescript
|
|
775
|
-
import SentiSense, {
|
|
418
|
+
import SentiSense, { NotFoundError, RateLimitError } from "sentisense";
|
|
776
419
|
|
|
777
420
|
try {
|
|
778
|
-
const
|
|
421
|
+
const price = await client.stocks.getPrice("AAPL");
|
|
779
422
|
} catch (error) {
|
|
780
|
-
if (error instanceof
|
|
781
|
-
|
|
782
|
-
} else if (error instanceof RateLimitError) {
|
|
783
|
-
if (error.code === "quota_exceeded") {
|
|
784
|
-
// 429: monthly allowance used up. Not retried; error.message says when it resets.
|
|
785
|
-
} else {
|
|
786
|
-
// 429: per-minute limit ("rate_limit_exceeded"), thrown once retries are used up.
|
|
787
|
-
// error.retryAfter is the server's wait in seconds.
|
|
788
|
-
}
|
|
789
|
-
}
|
|
423
|
+
if (error instanceof NotFoundError) console.log("Not covered:", error.code);
|
|
424
|
+
else if (error instanceof RateLimitError) console.log(error.message);
|
|
790
425
|
}
|
|
791
426
|
```
|
|
792
427
|
|
|
793
428
|
| Error class | HTTP status | When |
|
|
794
|
-
|
|
795
|
-
| `AuthenticationError` | 401, 403 |
|
|
796
|
-
| `NotFoundError` | 404 |
|
|
797
|
-
| `RateLimitError` | 429 |
|
|
798
|
-
| `
|
|
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 |
|
|
799
436
|
|
|
800
|
-
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.
|
|
801
438
|
|
|
802
439
|
## Links
|
|
803
440
|
|
|
804
|
-
-
|
|
805
|
-
-
|
|
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/)
|
|
806
443
|
- Changelog: [CHANGELOG.md](./CHANGELOG.md)
|
|
807
444
|
|
|
808
445
|
SentiSense provides research data for informational and educational purposes, not investment advice.
|