Entities

Search, retrieve, and analyze named entities extracted from articles. Entities include people, organizations, locations, and events — each tracked with mention counts, sentiment, and temporal distribution across sources.

List entities

GET /v1/entities

Search and retrieve entities matching a name or filter set. Results include mention frequency, average sentiment, and related entity references.

Parameter	Type	Description
query	string	Entity name or partial match. Case-insensitive.
type	enum	Filter by entity class: `PERSON` · `ORG` · `GPE` · `LOC` · `EVENT`
min_mentions	integer	Minimum occurrence count across all articles. Default: `1`
time_range	string	Lookback window: `1h`, `6h`, `24h`, `7d`, `30d`. Default: `24h`
limit	integer	Results per page. Max: `100`. Default: `20`

BASH

curl "https://api.polariapi.com/v1/entities?type=PERSON&query=Netanyahu&min_mentions=5" \
            -H "Authorization: Bearer pk_live_your_key"
          

{
          "entities": [
          {
          "name": "Benjamin Netanyahu",
          "type": "PERSON",
          "mention_count": 35,
          "first_seen": "2026-01-17T11:01:50Z",
          "last_seen": "2026-05-23T19:08:09Z",
          "article_ids": [
          "art_02711e1e71786df4",
          "art_0592893166abd068"
          ]
          }
          ],
          "total": 1,
          "query": "Netanyahu",
          "type_filter": null,
          "time_range": null
          }
        

Get entity

GET /v1/entities/{entity_id}

Retrieve full detail for a single entity — mention counts, sentiment over time, related entities, and the articles it appears in.

BASH

curl https://api.polariapi.com/v1/entities/ent_4k2m9x7p \
          -H "Authorization: Bearer pk_live_your_key"
        

Entity timeline

GET /v1/entities/{entity_id}/timeline

Returns the temporal distribution of mentions for an entity — how frequently it appeared across sources over time. Useful for detecting coverage spikes and narrative shifts.

Parameter	Type	Description
time_range	string	Lookback window. Default: `7d`
resolution	enum	Bucket size: `1h` · `6h` · `1d`. Default: `1d`

RESPONSE
{
          "entity": "Benjamin Netanyahu",
          "type_filter": null,
          "time_range": "7d",
          "total_mentions": 312,
          "timeline": [
          {
          "date": "2026-05-20",
          "type": "PERSON",
          "mention_count": 48,
          "article_ids": ["art_8f7h2k9s", "art_2m9k3x7f"]
          },
          {
          "date": "2026-05-21",
          "type": "PERSON",
          "mention_count": 91,
          "article_ids": ["art_3k9x2m7f"]
          }
          ]
          }
        

Entity sentiment

GET /v1/entities/{entity_name}/sentiment

Returns daily average sentiment for all articles mentioning a named entity. Scores range from -1.0 (strongly negative) to +1.0 (strongly positive), derived from cardiffnlp/twitter-roberta-base-sentiment-latest applied at ingest time.

Tip. Combine entity sentiment with the Clusters endpoint to correlate sentiment shifts with specific story clusters. Useful for brand monitoring, political coverage analysis, and crisis detection.

Parameter	Type	Description
entity_namepath	string	Entity name, case-insensitive. e.g. `Benjamin Netanyahu`.
type	enum	Optionally scope to a specific entity type to avoid name collisions.
time_range	string	Lookback window: `1h`, `6h`, `24h`, `7d`, `30d`. Default: `7d`

BASH

curl "https://api.polariapi.com/v1/entities/Benjamin%20Netanyahu/sentiment?time_range=30d"
          \
          -H "Authorization: Bearer pk_live_your_key"
        

RESPONSE
{
          "entity": "Benjamin Netanyahu",
          "type_filter": null,
          "time_range": "30d",
          "avg_sentiment": -0.312,
          "total_articles": 89,
          "timeline": [
          {
          "date": "2026-04-27",
          "avg_sentiment": -0.201,
          "article_count": 12,
          "distribution": {
          "positive": 2,
          "neutral": 5,
          "negative": 5
          }
          },
          {
          "date": "2026-04-28",
          "avg_sentiment": -0.489,
          "article_count": 21,
          "distribution": {
          "positive": 1,
          "neutral": 4,
          "negative": 16
          }
          }
          ]
          }
        

Entity types

The type field uses spaCy's NER label set. The five types exposed through the API:

Type	Description	Examples
`PERSON`	Named individuals	Benjamin Netanyahu, Elon Musk
`ORG`	Companies, agencies, institutions	Federal Reserve, Anthropic, NATO
`GPE`	Geopolitical entities — countries, cities, states	Iran, New York, European Union
`LOC`	Non-GPE locations — bodies of water, regions	Strait of Hormuz, Gulf of Mexico
`EVENT`	Named events	COP30, G7 Summit, Super Bowl

Note. Entity extraction is performed by Layer 1 using spaCy's NER pipeline. Common variant forms (e.g. "Trump" → "Donald Trump", "U.S." → "United States") are normalized at extraction time via an alias map. Less common variants may still be stored separately.

← Previous

Clusters