A social insights API for ad generation platforms. It provides structured signals, like psychographics, behavioral insights, trends, and audience language, to help AI models generate relevant, higher-converting ads.
List breaking entities (players or teams) for a vertical.
Entity kind to rank: 'player' or 'team'
Ranking mode: 'recommended' (default, balanced), 'rising' (biggest movers vs own baseline), 'top' (highest absolute volume), or 'newest' (most recently appeared). Legacy aliases (blended, hot, momentum, emerging, importance, recent, new) are accepted.
Vertical; only 'sports'
Filter to entities carrying this tag (e.g. a sport). Use a tag value from the /entities/breakout/tags endpoint.
Filter to entities with an event that has this timing relative to now: 'upcoming' (not yet started), 'ongoing' (in progress), or 'past'. Only entities tied to a scheduled event have a timing, so this narrows results to them and to their matching events.
Filter to entities involved in a specific event, by name (e.g. 'world cup'). An unrecognized event returns no entities.
Max entities
Pagination offset
Only entities whose most recently appeared topic was first seen within this many hours (the 'brand new' filter). Omit for no limit.
curl 'https://api.upriver.ai/v1/entities/breakout?entity_type=' \
--header 'X-API-Key: YOUR_SECRET_TOKEN'
{
"entities": [
{
"entity_id": "string",
"name": "string",
"entity_type": "string",
"score": 1,
"velocity": 1,
"trend_direction": "string",
"last_activity_at": "2026-09-05T06:49:26.587Z",
"top_topics": [
{
"topic_id": "string",
"name": "string",
"citations": [
{
"source_category": "string",
"source_url": "string",
"title": "string",
"display": ""
}
],
"source_summary": {
"additionalProperty": 1
},
"citation_rate": [
{
"day": "string",
"count": 1
}
],
"last_activity_at": "2026-09-05T06:49:26.587Z"
}
]
}
],
"total_count": 1
}