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? Use the urlSlug when you want quick and memorable: it is stable in practice and only changes if an entity is genuinely renamed. For long-lived references, like a product tracker that must keep working across renames, store the entity id in its URL-safe dashed form (replace / with -, for example kb-person-65): it is permanent and never changes. Both forms are accepted anywhere an {entityId} is expected.

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
  }
]

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

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

---

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