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.
Search breakout topics using hybrid vector + keyword search.
Supports three search modes:
Request for searching breakout topics.
Search query text
Entitled private feed whose Breakout topics should be searched.
Filter by vertical (e.g., 'sports')
Search mode: vector, keyword, hybrid
Return raw topics or deduped derived story surfaces
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: ["citations", "entities"]
Deprecated: use include=["citations","entities"] instead.
Optional source-aware context for query rewriting. Useful for terse external prompts such as Kalshi markets.
Optional Kalshi event URL or ticker. When provided, the server resolves event metadata and uses it for query planning. Mutually exclusive with query_context.
Restrict returned citations to these source categories (news, reddit, twitter). Omit for all sources. Only applies when surface_mode=topic.
Enable enhanced relevance scoring for search results. When true, results are scored and re-ranked by how well they match the query intent.
curl https://api.upriver.ai/v1/topics/breakout/search \
--request POST \
--header 'Content-Type: application/json' \
--header 'X-API-Key: YOUR_SECRET_TOKEN' \
--data '{
"query": "",
"feed": "",
"vertical": "",
"mode": "hybrid",
"surface_mode": "topic",
"limit": 20,
"include": [
"citations"
],
"include_citations": false,
"query_context": {
"source": "",
"series_title": "",
"market_subtitle": "",
"competition": "",
"competition_scope": "",
"contract_tickers": [
""
],
"contract_titles": [
""
],
"contract_subtitles": [
""
]
},
"kalshi_event_url": "",
"citation_sources": [
"news"
],
"llm_relevance": true
}'
{
"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"
]
}
}
],
"search_mode": "string"
}