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 breakout topics with optional filters.
Returns topics ranked by the specified sort mode (recommended / rising / top / newest); see the sort_by parameter. Legacy relevance/importance still work.
Entitled private feed whose Breakout topics should be listed.
Filter by vertical: 'sports', 'tech', or 'politics'
Filter by category within the sports vertical (topic mode only), e.g. 'nba' or 'nfl'
Filter by topic status. Options: 'active' (default), 'detected', 'emerging', 'trending', 'declining', or 'all'.
Filter options for topic status.
Note: archived is intentionally absent — archived topics are always
excluded from browse/list surfaces, so it is not an accepted filter value.
Filter to topics about an event with this timing relative to now: 'upcoming' (not yet started), 'ongoing' (in progress), or 'past'. Only topics tied to a scheduled event have a timing, so this narrows results to them.
Maximum number of results. Requesting more than 20 results requires a credits-based plan.
Optional expansions to include in the response. Allowed values: citations, entities. Example: include=citations&include=entities
Restrict returned citations to these source categories (news, reddit, twitter). Omit for all sources. Only applies when surface_mode=topic.
Citation source categories usable as a citation filter.
A subset of the source_category values that appear on returned citations —
the categories worth filtering on. Other categories (web, tiktok, trends) can
still appear on citations but are not offered as filter values.
Ranking mode: 'recommended' (default, balanced), 'rising' (gaining fastest), 'top' (highest absolute volume), or 'newest' (most recently appeared). Legacy aliases (relevance, importance, hot, blended, momentum, emerging, recent, new) are accepted.
Keep only topics first seen within this many hours (the 'brand new' filter). Combine with any sort. Omit for no limit.
Inclusive ISO 8601 lower bound for the result's earliest_evidence_at. Use it to restrict results to activity that first appeared within a recent window. Results with earlier dated evidence, or with no dated evidence, are excluded as a whole; evidence returned within a matching result is not time-filtered. The comparison uses all known supporting evidence, including records omitted by response filters or limits. Supported when surface_mode=topic.
List raw topics or deduped derived story surfaces
List surface mode for breakout browse responses.
curl https://api.upriver.ai/v1/topics/breakout \
--header 'X-API-Key: YOUR_SECRET_TOKEN'
{
"surface_mode": "topic",
"topics": [
{
"topic_id": "string",
"topic_name": "string",
"vertical": "string",
"category": "string",
"status": "string",
"score": 1,
"relevance_score": 1,
"engagement": {
"percentile_score": 1
},
"peak_score": 1,
"confidence_score": 1,
"discovered_at": "2026-09-05T06:49:26.587Z",
"earliest_evidence_at": "2026-09-05T06:49:26.587Z",
"last_signal_at": "2026-09-05T06:49:26.587Z",
"updated_at": "2026-09-05T06:49:26.587Z",
"source_summary": {
"additionalProperty": 1
},
"citations": [
{
"source_category": "string",
"source_url": "string",
"title": "string",
"display": "",
"snippet": "string",
"source_authority": 1,
"engagement_score": 1,
"published_at": "2026-09-05T06:49:26.587Z"
}
],
"entities": [
{
"canonical_name": "string",
"entity_id": "string",
"entity_type": "string",
"confidence": 1,
"entity_subtype": "string"
}
],
"trend": {
"momentum": 0,
"direction": "up"
},
"citation_rate": [
{
"day": "string",
"count": 1
}
],
"narrative": {
"narrative_id": "string",
"display_name": "string",
"member_count": 1,
"arc_summary": [
"string"
]
},
"temporal_status": "upcoming",
"event_start_at": "2026-09-05T06:49:26.587Z",
"event_end_at": "2026-09-05T06:49:26.587Z"
}
],
"stories": [
{
"requested_view": "cluster",
"seed_topic": {
"topic_id": "string",
"topic_name": "string",
"vertical": "string",
"category": "string",
"status": "string",
"score": 1,
"relevance_score": 1,
"engagement": {
"percentile_score": 1
},
"peak_score": 1,
"confidence_score": 1,
"discovered_at": "2026-09-05T06:49:26.587Z",
"earliest_evidence_at": "2026-09-05T06:49:26.587Z",
"last_signal_at": "2026-09-05T06:49:26.587Z",
"updated_at": "2026-09-05T06:49:26.587Z",
"source_summary": {
"additionalProperty": 1
},
"citations": [
{
"source_category": "string",
"source_url": "string",
"title": "string",
"display": "",
"snippet": "string",
"source_authority": 1,
"engagement_score": 1,
"published_at": "2026-09-05T06:49:26.587Z"
}
],
"entities": [
{
"canonical_name": "string",
"entity_id": "string",
"entity_type": "string",
"confidence": 1,
"entity_subtype": "string"
}
],
"trend": {
"momentum": 0,
"direction": "up"
},
"citation_rate": [
{
"day": "string",
"count": 1
}
],
"narrative": {
"narrative_id": "string",
"display_name": "string",
"member_count": 1,
"arc_summary": [
"string"
]
},
"temporal_status": "upcoming",
"event_start_at": "2026-09-05T06:49:26.587Z",
"event_end_at": "2026-09-05T06:49:26.587Z"
},
"surface": {
"story_id": "string",
"surface_type": "topic",
"member_topic_ids": [
"string"
],
"lead_topic_id": "string",
"display_name": "string",
"description": "string",
"story_score": 1,
"latest_signal_at": "2026-09-05T06:49:26.587Z",
"member_count": 1,
"coherence_score": 1,
"projection_refreshed_at": "2026-09-05T06:49:26.587Z"
},
"member_topics": [
{
"topic_id": "string",
"topic_name": "string",
"vertical": "string",
"category": "string",
"status": "string",
"score": 1,
"relevance_score": 1,
"engagement": {
"percentile_score": 1
},
"peak_score": 1,
"confidence_score": 1,
"discovered_at": "2026-09-05T06:49:26.587Z",
"earliest_evidence_at": "2026-09-05T06:49:26.587Z",
"last_signal_at": "2026-09-05T06:49:26.587Z",
"updated_at": "2026-09-05T06:49:26.587Z",
"source_summary": {
"additionalProperty": 1
},
"citations": [
{
"source_category": "string",
"source_url": "string",
"title": "string",
"display": "",
"snippet": "string",
"source_authority": 1,
"engagement_score": 1,
"published_at": "2026-09-05T06:49:26.587Z"
}
],
"entities": [
{
"canonical_name": "string",
"entity_id": "string",
"entity_type": "string",
"confidence": 1,
"entity_subtype": "string"
}
],
"trend": {
"momentum": 0,
"direction": "up"
},
"citation_rate": [
{
"day": "string",
"count": 1
}
],
"narrative": {
"narrative_id": "string",
"display_name": "string",
"member_count": 1,
"arc_summary": [
"string"
]
},
"temporal_status": "upcoming",
"event_start_at": "2026-09-05T06:49:26.587Z",
"event_end_at": "2026-09-05T06:49:26.587Z"
}
],
"search_match": {
"matched_topic_ids": [
"string"
],
"matched_topic_count": 1,
"match_sources": [
"string"
]
}
}
],
"story_source": "auto",
"total_count": 1,
"source_topic_count": 1,
"returned_story_count": 1,
"next_cursor": "string"
}