Entities API

Overview

The SentiSense ontology tracks not just stocks but the people, products, and organizations that move them: executives, politicians, central bankers, flagship products, regulators. Every one of them has the same metrics surface as a stock: the SentiSense Score, sentiment, mentions, and social dominance time series from the Metrics API.

This page documents how to find an entity's handle. The returned urlSlug (or ticker) plugs straight into the Metrics API {entityId} parameter.

The urlSlug is also the web handle: https://app.sentisense.ai/entities/{urlSlug} opens that entity in the app, for example Anthropic or ChatGPT.

Which handle should you store? The urlSlug, or the ticker for a listed company. It is the only identifier the API accepts anywhere an {entityId} is expected, and it is stable in practice: it changes only if an entity is genuinely renamed. Internal KB ids, including the dashed kb-person-65 form, are not part of the public API and resolve to nothing here. If a rename ever breaks a stored handle, GET /api/v1/kb/entities/search?q= finds the entity again by name.

What you can build with this:

• Track a person's SentiSense Score. How is the market conversation on Jerome Powell trending this month?
• Watch a politician's sentiment around a trade disclosure. Nancy Pelosi's sentiment and mention volume, day by day.
• Compare an executive against their company. Does the crowd feel differently about Jensen Huang than about NVDA?
• Follow a product, not just its maker. Mentions of a flagship product can move before the parent ticker does.

Access: API key required, available on every tier. Requests count against your monthly quota and per-minute rate limit.

Building an AI agent? See Entity sentiment API: track sentiment for CEOs, politicians, and products for a worked end-to-end example: search a person by name, then pull their sentiment time series with the handle you get back.

---

GET /entities/search

Returns the best-matching entities for a query, scored across names, aliases, tickers, and slugs (exact matches first, then prefix, then substring).

This is a resolution endpoint, not an enumeration one: queries must be at least 2 characters and results are capped, so you look up entities you already know about rather than paging through the catalog.

Parameters:

Parameter	Type	Required	Default	Description
q	string	Yes	-	Case-insensitive name, alias, ticker, or slug fragment (minimum 2 characters)
type	string	No	all	Filter: company, country, etf, organization, person, product, topic
limit	int	No	10	Maximum results (capped at 25)

Example Request:

curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/kb/entities/search?q=pelosi&type=person"

Response: array of matches, best first:

[
  {
    "name": "Nancy Pelosi",
    "urlSlug": "Nancy-Pelosi",
    "type": "person",
    "ticker": null
  }
]

A company match carries two extra fields:

[
  {
    "name": "Samsung Electronics Co., Ltd.",
    "urlSlug": "Samsung-Electronics-Co-Ltd",
    "type": "company",
    "ticker": null,
    "listingCoverage": "public_untracked",
    "listing": "KRX: 005930"
  }
]

Field	Type	Description
name	string	Display name
urlSlug	string	Canonical handle for the Metrics API {entityId} parameter
type	string	company, country, etf, organization, person, product, or topic
ticker	string|null	Primary ticker for companies and ETFs; null otherwise
listingCoverage	string | absent	Companies only: public_tracked (listed on a market we price), public_untracked (listed on a market we do not price), or private (not listed). Absent for every other entity type
listing	string | absent	The untracked listing as one string, e.g. "KRX: 005930". Present only alongside listingCoverage: "public_untracked"

A public_untracked company has no ticker, no price series and no /stocks/{ticker} page; it can still be searched and queried for sentiment, mentions and Score, and listing is what to show in place of a ticker.

Returns 400 invalid_parameter when q is under 2 characters or type is not one of the listed values.

listingCoverage is a different question from listingStatus on GET /stocks/{ticker}/price, which is the delisting lifecycle (DELISTED, PENDING_DELISTING) of a symbol we do price.

---

GET /entities/popular

Returns a small curated list of high-profile entities (major CEOs, political figures, the Federal Reserve). Useful as a seed list for autocomplete or a "trending people" widget without issuing a search.

Example Request:

curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/kb/entities/popular"

Response: array of entities. Each entry:

Field	Type	Description
displayName	string	Entity display name
type	string	PERSON, ORGANIZATION, etc.
urlSlug	string|null	Handle for the Metrics API {entityId} parameter
relatedStock	string|null	Ticker of the most closely associated stock, when there is one

---

Worked examples

Check a person's SentiSense Score. Resolve the handle once, then query any metric:

# 1. Resolve the handle
curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/kb/entities/search?q=jensen%20huang"
# -> [{"name": "Jensen Huang", "urlSlug": "Jensen-Huang", "type": "person", "ticker": null}]

# 2. SentiSense Score time series for that person
curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v2/metrics/entity/Jensen-Huang/metric/sentisense"

Politician sentiment and mention volume:

curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v2/metrics/entity/Nancy-Pelosi/metric/sentiment"
curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v2/metrics/entity/Nancy-Pelosi/metric/mentions"

Executive vs company. Same metric, two handles, one comparison:

curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v2/metrics/entity/Jensen-Huang/metric/sentiment"
curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v2/metrics/entity/NVDA/metric/sentiment"

The metric response format (time-ordered points with a flat value scalar) is documented in the Metrics API.

Related discovery surfaces:

• GET /api/v1/stocks/{ticker}/entities: the entities related to one stock (executives, products), each carrying its urlSlug (see the Stocks API)
• Identifier semantics across all endpoints: the Entity Identifiers section of the API Overview