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.
Get the best available derived story surface around a seed topic.
Breakout topic UUID returned by GET /v1/topics/breakout or POST /v1/topics/breakout/search. Do not pass raw query text or domains.
Optional related data to include. Allowed: "citations", "entities".
Deprecated: use include=["citations","entities"] instead.
Entitled private feed that returned this topic.
curl 'https://api.upriver.ai/v1/topics/breakout/{topic_id}/story' \
--header 'X-API-Key: YOUR_SECRET_TOKEN'
{
"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"
]
}
}