Entities

Query the entities D2TR extracts from every article — people, organizations, products, places — and the articles that mention them.

Entities are the named people, organizations, places and things extracted and merged across Discover articles. These endpoints read the merged-entity table directly: they scan and aggregate it in memory per request, so expect higher latency than the indexed article endpoints. Every entity endpoint requires an API key and is region-scoped — a country-restricted key only ever sees entities that appear on whitelisted-country URLs.

#List entities

GET/v1/entitiesAPI key

Lists unique entities across all articles, deduped by normalized_name (keeping the highest-scoring occurrence). Results are sorted by unified_score descending, then paginated.

Query parameters

searchstringoptional: Case-insensitive substring match on the entity name.
entity_typestringoptional: Keep only entities whose entity_types array contains this exact value (for example SportsTeam).
min_scorenumberoptionaldefault 0.0: Minimum unified_score. Must be >= 0.0.
limitintegeroptionaldefault 50: Page size, 1–200.
offsetintegeroptionaldefault 0: Number of entities to skip. Must be >= 0.

curl

curl "https://d2tr.com/api/v1/entities?search=ballers&entity_type=SportsTeam&min_score=0.5&limit=2" \
  -H "X-API-Key: $D2TR_API_KEY"

Response

{
  "entities": [
    {
      "name": "Example City Ballers",
      "normalized_name": "example city ballers",
      "unified_score": 0.87,
      "embedding_similarity": 0.79,
      "source": "razor",
      "entity_types": ["Organization", "SportsTeam"],
      "wikipedia_url": "https://en.wikipedia.org/wiki/Example_City_Ballers",
      "kg": {
        "id": "/g/11abc",
        "name": "Example City Ballers",
        "description": "Professional basketball team",
        "image_url": "https://kg.example.com/ballers.png"
      },
      "url_id": "b3f1c2a0-..."
    }
  ],
  "total": 1,
  "limit": 2,
  "offset": 0
}

GET/v1/entities/trendingAPI key

Entities ranked by mention count within a recent time window for a specific region. This is a top-N list — there is no offset or total. region is required; a restricted key requesting a disallowed region gets 403.

Query parameters

regionstringrequired: ISO-3166-1 alpha-2 country code (for example US), compared case-insensitively against the profile country.
periodstringoptionaldefault 24h: Window ending now (UTC). One of 1h, 6h, 24h, 7d.
entity_typestringoptional: Keep only entities whose entity_types array contains this value.
langstringoptional: Restrict to profiles with this language code.
limitintegeroptionaldefault 20: Number of top entities to return, 1–100.

curl

curl "https://d2tr.com/api/v1/entities/trending?region=US&period=24h&limit=2" \
  -H "X-API-Key: $D2TR_API_KEY"

Response

{
  "region": "US",
  "period": "24h",
  "trending_entities": [
    {
      "name": "Example City Ballers",
      "kg_id": "/g/11abc",
      "kg_name": "Example City Ballers",
      "entity_types": ["Organization", "SportsTeam"],
      "mentions_in_period": 58,
      "articles_in_period": 21,
      "top_article": {
        "url_id": "b3f1c2a0-...",
        "title": "Finals recap: an instant classic",
        "domain": "example-sports.com"
      }
    }
  ]
}

#Get an entity

GET/v1/entities/{entity_name}API key

Detail for a single entity, matched by normalized name. Returns the highest-scoring occurrence plus a count of articles mentioning it. The entity_name path segment is matched by lower().strip() against normalized_name, so URL-encode names with spaces (for example Example%20City%20Ballers).

Path parameters

entity_namestringrequired: The entity name to look up. Matched case-insensitively and trimmed against normalized_name.

curl

curl "https://d2tr.com/api/v1/entities/Example%20City%20Ballers" \
  -H "X-API-Key: $D2TR_API_KEY"

Response

{
  "name": "Example City Ballers",
  "normalized_name": "example city ballers",
  "unified_score": 0.87,
  "embedding_similarity": 0.79,
  "source": "razor",
  "entity_types": ["Organization", "SportsTeam"],
  "wikipedia_url": "https://en.wikipedia.org/wiki/Example_City_Ballers",
  "kg_id": "/g/11abc",
  "kg_name": "Example City Ballers",
  "kg_description": "Professional basketball team",
  "kg_image_url": "https://kg.example.com/ballers.png",
  "articles_count": 21
}

#Articles for an entity

GET/v1/entities/{entity_name}/articlesAPI key

All articles that mention a given entity, sorted by the entity’s unified_score in each article (descending), then paginated. A restricted key only sees whitelisted-country articles.

Parameters

entity_namestringrequired: Path segment. Matched by lower().strip() against normalized_name; URL-encode spaces.
limitintegeroptionaldefault 50: Page size, 1–200.
offsetintegeroptionaldefault 0: Number of articles to skip. Must be >= 0.

curl

curl "https://d2tr.com/api/v1/entities/Example%20City%20Ballers/articles?limit=2" \
  -H "X-API-Key: $D2TR_API_KEY"

Response

{
  "entity_name": "Example City Ballers",
  "articles": [
    {
      "url_id": "b3f1c2a0-...",
      "url": "https://example-sports.com/finals-recap",
      "title": "Finals recap: an instant classic",
      "domain": "example-sports.com",
      "published_at": "2026-06-28T22:10:00+00:00",
      "unified_score": 0.87,
      "embedding_similarity": 0.79,
      "source": "razor",
      "summary": "A last-second shot decided the championship..."
    }
  ],
  "total": 21
}

Entities

#List entities

#Trending entities

#Get an entity

#Articles for an entity