Threat intelligence API / Reference / Entities

Entities endpoints

Threat actors, malware, tools, companies, products, CVEs, countries and industries, with profiles and the incidents they appear in.

GET /entities/search · GET /entities/{entity_type}/{entity_value}/related · GET /entities/{entity_type}/{entity_value}/cooccurring-cves · GET /entities/{category}/{entity_value} · GET /entities/trending

GET /entities/search

Search entities · 1 credit per call

Search entities.

Query parameters

q: Search query
entity_type: Filter by type (optional)
limit: Max results (default: 20, max: 100)
offset: Skip N results for pagination (default: 0)
with_cve_count: Include a `cve_count` per entity (distinct CVEs co-occurring

with it). Adds a correlated subquery, so it's opt-in — leave off for autocomplete/typeahead where latency matters.

Returns matching entities with frequency data + pagination metadata (total, limit, offset) so consumers can page beyond the first 100.

Parameters

Name	In	Type
q	query	string
entity_type	query	string
limit	query	integer
offset	query	integer
with_cve_count	query	boolean

Response 200 · EntitiesSearchResponse

Field	Type	Meaning
entities *	array of EntitySearchItem
count *	integer
total	integer or null
limit	integer or null
offset	integer or null
query	string or null
entity_type	string or null

curl -H "X-API-Key: $TC_KEY" \
  "https://threatcluster.io/api/public/v1/entities/search"

GET /entities/{entity_type}/{entity_value}/related

Related entities · 1 credit per call

Get entities that co-occur in the same clusters as the target entity.

Path parameters

entity_type: Entity type (malware, apt-group, tool, campaign, etc.)
entity_value: Entity value (URL-encoded)

Query parameters

limit: Max related entities (default 25, max 50)
sub: Include sub-relationships between related entities (default true)

Returns related entities with shared cluster counts, plus pairwise sub-relationships.

Parameters

Name	In	Type	Required
entity_type	path	string	yes
entity_value	path	string	yes
limit	query	integer
sub	query	boolean

Response 200 · RelatedEntitiesResponse

Field	Type	Meaning
entity_type *	string
entity_value *	string
related *	array of RelatedEntity
sub_relationships	null or null

curl -H "X-API-Key: $TC_KEY" \
  "https://threatcluster.io/api/public/v1/entities/{entity_type}/{entity_value}/related"

GET /entities/{entity_type}/{entity_value}/cooccurring-cves

Co-occurring CVEs for an entity · 1 credit per call

CVEs that co-occur with this entity in articles (mentioned alongside it), newest-first and paginated. This is the full set the search endpoint's `cve_count` reports — use it to page through every co-occurring CVE, not the capped co_entities bucket in the entity-detail response.

Query parameters

page: Page number (default 1)
limit: Results per page (default 20, max 100)

Parameters

Name	In	Type	Required
entity_type	path	string	yes
entity_value	path	string	yes
page	query	integer
limit	query	integer

Response 200 · CooccurringCvesResponse

Field	Type	Meaning
entity_type *	string
entity_value *	string
cves *	array of CooccurringCveItem
total *	integer
page *	integer
limit *	integer
pages *	integer

curl -H "X-API-Key: $TC_KEY" \
  "https://threatcluster.io/api/public/v1/entities/{entity_type}/{entity_value}/cooccurring-cves"

GET /entities/{category}/{entity_value}

Entity detail · 1 credit per call

Get entity details with related clusters.

Path parameters

category: Entity type (cve, malware, apt-group, etc.)
entity_value: Entity value (URL-encoded)

Returns entity info, related clusters, and articles.

Parameters

Name	In	Type	Required	Meaning
category	path	string	yes
entity_value	path	string	yes

Response 200 · EntityDetailsResponse

Field	Type	Meaning
entity *	EntityInfo
overview	string or null
recent_events	string or null
clusters	array or null
articles	array or null
co_entities	object or null
co_entities_with_counts	object or null
aliases	array or null

curl -H "X-API-Key: $TC_KEY" \
  "https://threatcluster.io/api/public/v1/entities/{category}/{entity_value}"

GET /entities/trending

Trending entities by type · 1 credit per call

Get trending entities across all types.

Query parameters

time_filter: 7d, 30d (default: 7d)
limit: Max per type (default: 10, max: 50)

Returns trending entities grouped by type with change indicators.

Parameters

Name	In	Type	Required	Meaning
time_filter	query	string
limit	query	integer

Response 200 · EntitiesTrendingResponse

Field	Type	Meaning
trending *	object	Keyed by entity type (apt_group, malware, ...)
time_filter	string or null
limit_per_type	integer or null

curl -H "X-API-Key: $TC_KEY" \
  "https://threatcluster.io/api/public/v1/entities/trending"