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 and how to read what we know about it: its curated facts and how it relates to the companies, people, and products around it. 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

---

GET /entities/{entityId}

Returns one entity: who or what it is, the facts the knowledge graph holds about it, and up to eight related entities, each labelled with the relationship that ties it to this one. {entityId} is the entity's urlSlug (or ticker for a listed company), as returned by search.

Parameters:

Parameter	Type	Required	Default	Description
entityId	path	Yes	-	The entity's handle (urlSlug), e.g. Anthropic, Jensen-Huang, Claude

Example Request:

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

Response:

{
  "entity": {
    "id": "kb/person/0",
    "displayName": "Jensen Huang",
    "type": "PERSON",
    "relatedStock": "NVDA",
    "iconUrl": null,
    "title": "CEO, Founder",
    "category": null,
    "urlSlug": "Jensen-Huang"
  },
  "description": "Co-founder, president and chief executive officer of NVIDIA.",
  "profile": {
    "roles": [
      {
        "role": "CEO",
        "since": "1993",
        "company": { "name": "NVIDIA Corporation", "urlSlug": "NVIDIA-Corporation", "type": "COMPANY", "ticker": "NVDA", "listingCoverage": "public_tracked" }
      }
    ],
    "founderOf": [
      { "year": "1993", "company": { "name": "NVIDIA Corporation", "urlSlug": "NVIDIA-Corporation", "type": "COMPANY", "ticker": "NVDA", "listingCoverage": "public_tracked" } }
    ],
    "nationality": "Taiwanese-American"
  },
  "latestMetrics": { "sentiment": 0.12, "mentions": 85.0, "sentisense_score": 14.3 },
  "relatedEntities": [
    {
      "id": "kb/company/0",
      "displayName": "NVIDIA Corporation",
      "type": "STOCK",
      "relatedStock": "NVDA",
      "iconUrl": null,
      "title": null,
      "category": null,
      "urlSlug": "NVIDIA-Corporation",
      "listingCoverage": "public_tracked",
      "relation": { "type": "LEADS", "direction": "outbound", "properties": { "role": "CEO", "since": "1993" } }
    },
    {
      "id": "kb/product/0",
      "displayName": "GeForce RTX",
      "type": "PRODUCT",
      "relatedStock": "NVDA",
      "iconUrl": null,
      "title": null,
      "category": "graphics_card",
      "urlSlug": "GeForce-RTX",
      "relation": {
        "type": "PRODUCT_OF",
        "direction": "inbound",
        "via": { "name": "NVIDIA Corporation", "urlSlug": "NVIDIA-Corporation", "type": "COMPANY", "ticker": "NVDA", "listingCoverage": "public_tracked" }
      }
    }
  ]
}

Metric values in the example are illustrative.

Top-level fields:

Field	Type	Description
entity	object	The entity itself (fields below)
description	string | absent	Curated one-line summary. Absent when the knowledge graph has none
profile	object | absent	Curated facts (fields below). Absent when the entity has none
latestMetrics	object	7-day averages keyed sentiment, mentions, sentisense_score. A key is missing when the entity has no reading in the window; the full series are on the Metrics API
relatedEntities	array	Up to eight related entities, closest relationship first, in the entity shape plus relation

entity and relatedEntities[] fields:

Field	Type	Description
displayName	string	Display name
type	string	PERSON, PRODUCT, ORGANIZATION, COMPANY, TOPIC, COUNTRY; a related listed company is STOCK
urlSlug	string | null	The handle: use it for the Metrics API and for https://app.sentisense.ai/entities/{urlSlug}
relatedStock	string | null	The entity's own ticker for a listed company, otherwise the most closely associated ticker
title	string | null	People: their title, e.g. "CEO, Founder"
category	string | null	Products: the product category, snake_case (ai_assistant). Topics: the topic's area (Technology). Organizations: the kind of organization (Central Bank)
listingCoverage, listing	string | absent	Companies only, same meaning as in search above
appId	string | absent	Apple App Store id, for products with a tracked app
id	string	Internal identifier. It is not a handle: do not store it or pass it back, use urlSlug
iconUrl	null	Reserved
relation	object | absent	relatedEntities[] only: how this row relates to the requested entity (below)

profile fields (every key is absent when the knowledge graph has no value for it):

Field	Type	Who has it	Description
about	string	any, when curated	A few sentences on what the entity is and does. description stays the one-line summary
category	string	products, topics, organizations	Same value as entity.category
aliases	string[]	products, people, companies, organizations	Other names the entity goes by, up to eight
maker	ref	products	The company that makes the product
family	ref	product variants	The product family a model or generation belongs to
introduced, retired	string	product variants	When the variant was introduced or retired, "YYYY-MM" or "YYYY"
modelLines	object[]	product families	Every tracked variant, newest first: {name, urlSlug, introduced, retired}
appStoreUrl	string	products with an iOS app	Apple App Store link
xHandle	string	any	X (Twitter) handle, without the @
roles	object[]	people	Leadership roles, current first: {role, since, until, company}
founderOf	object[]	people	Companies the person founded: {year, company}
nationality	string	people
founded	string	companies, organizations	Founding year
headquarters	string	companies, organizations

A ref is {name, urlSlug, type, ticker, listingCoverage, listing}: ticker appears only for a listed company (its stock page is /stocks/{ticker}), listingCoverage only for companies, listing only alongside public_untracked.

relation fields:

Field	Type	Description
type	string	LEADS, FOUNDED, PRODUCT_OF, VARIANT_OF, SUBTOPIC_OF, SUBSIDIARY_OF, OWNS, or PEER, the edge types of the stock graph. PRODUCT_OF ties a product to its maker
direction	string	outbound when the requested entity is the edge's source (on Jensen Huang's page, NVIDIA's row is LEADS outbound), inbound when the related entity is (on NVIDIA's page, Jensen Huang's row is LEADS inbound), mutual for PEER
properties	object | absent	role, since, until on LEADS; year on FOUNDED; the variant's introduced and retired on VARIANT_OF
via	ref | absent	Present when the row is two steps away, reached through the requested entity's company: another leader or product of that company, or one of its peers. type and direction then describe the row's tie to via

A person who currently leads a company they also founded is related to it by LEADS (with the role); a former leader who founded it, by FOUNDED.

Returns 404 when the handle does not resolve to an entity.

---

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
• How a name resolves to one typed node, with the calls that read the graph: the knowledge graph behind stock sentiment