Breakout Topics
Get Topic Story View
Get the best available derived story surface around a seed topic.
GET
/
v1
/
topics
/
breakout
/
{topic_id}
/
story
Get Topic Story View
curl --request GET \
--url https://api.upriver.ai/v1/topics/breakout/{topic_id}/story \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.upriver.ai/v1/topics/breakout/{topic_id}/story"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.upriver.ai/v1/topics/breakout/{topic_id}/story', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.upriver.ai/v1/topics/breakout/{topic_id}/story",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.upriver.ai/v1/topics/breakout/{topic_id}/story"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.upriver.ai/v1/topics/breakout/{topic_id}/story")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.upriver.ai/v1/topics/breakout/{topic_id}/story")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"seed_topic": {
"topic_id": "<string>",
"topic_name": "<string>",
"canonical_name": "<string>",
"vertical": "<string>",
"status": "<string>",
"peak_score": 123,
"discovered_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"category": "<string>",
"score": 123,
"relevance_score": 123,
"engagement": {
"percentile_score": 123
},
"confidence_score": 123,
"last_signal_at": "2023-11-07T05:31:56Z",
"source_summary": {},
"citations": [
{
"source_category": "<string>",
"source_url": "<string>",
"title": "<string>",
"display": "",
"snippet": "<string>",
"source_authority": 123,
"engagement_score": 123,
"published_at": "2023-11-07T05:31:56Z"
}
],
"entities": [
{
"canonical_name": "<string>",
"entity_type": "<string>",
"confidence": 123,
"entity_id": "<string>",
"entity_subtype": "<string>"
}
],
"trend": {
"momentum": 1
},
"citation_rate": [
{
"day": "<string>",
"count": 123
}
],
"narrative": {
"narrative_id": "<string>",
"display_name": "<string>",
"member_count": 123,
"arc_summary": [
"<string>"
]
},
"event_start_at": "2023-11-07T05:31:56Z",
"event_end_at": "2023-11-07T05:31:56Z"
},
"surface": {
"story_id": "<string>",
"member_topic_ids": [
"<string>"
],
"display_name": "<string>",
"story_score": 123,
"member_count": 123,
"lead_topic_id": "<string>",
"description": "<string>",
"latest_signal_at": "2023-11-07T05:31:56Z",
"coherence_score": 123,
"projection_refreshed_at": "2023-11-07T05:31:56Z"
},
"member_topics": [
{
"topic_id": "<string>",
"topic_name": "<string>",
"canonical_name": "<string>",
"vertical": "<string>",
"status": "<string>",
"peak_score": 123,
"discovered_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"category": "<string>",
"score": 123,
"relevance_score": 123,
"engagement": {
"percentile_score": 123
},
"confidence_score": 123,
"last_signal_at": "2023-11-07T05:31:56Z",
"source_summary": {},
"citations": [
{
"source_category": "<string>",
"source_url": "<string>",
"title": "<string>",
"display": "",
"snippet": "<string>",
"source_authority": 123,
"engagement_score": 123,
"published_at": "2023-11-07T05:31:56Z"
}
],
"entities": [
{
"canonical_name": "<string>",
"entity_type": "<string>",
"confidence": 123,
"entity_id": "<string>",
"entity_subtype": "<string>"
}
],
"trend": {
"momentum": 1
},
"citation_rate": [
{
"day": "<string>",
"count": 123
}
],
"narrative": {
"narrative_id": "<string>",
"display_name": "<string>",
"member_count": 123,
"arc_summary": [
"<string>"
]
},
"event_start_at": "2023-11-07T05:31:56Z",
"event_end_at": "2023-11-07T05:31:56Z"
}
],
"search_match": {
"matched_topic_count": 123,
"matched_topic_ids": [
"<string>"
],
"match_sources": [
"<string>"
]
}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Authorizations
Path Parameters
Breakout topic UUID returned by GET /v1/topics/breakout or POST /v1/topics/breakout/search. Do not pass raw query text or domains.
Query Parameters
Optional related data to include. Allowed: "citations", "entities".
Available options:
citations, entities Deprecated: use include=["citations","entities"] instead.
Response
Successful Response
Response for a cluster/timeline/story surface seeded by one topic.
Requested derived view
Available options:
cluster, story, timeline Seed topic
Show child attributes
Show child attributes
Resolved story surface
Show child attributes
Show child attributes
Hydrated member topics in surface order
Show child attributes
Show child attributes
Search-only metadata explaining why this story matched
Show child attributes
Show child attributes
Previous
Media Categories SearchFind the most relevant categories from the taxonomy for a given freeform text. Useful for discovering the best category for brand industries, target audiences, etc. Returns ordered matches with confidence scores.
Next
⌘I
Get Topic Story View
curl --request GET \
--url https://api.upriver.ai/v1/topics/breakout/{topic_id}/story \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.upriver.ai/v1/topics/breakout/{topic_id}/story"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.upriver.ai/v1/topics/breakout/{topic_id}/story', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.upriver.ai/v1/topics/breakout/{topic_id}/story",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.upriver.ai/v1/topics/breakout/{topic_id}/story"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.upriver.ai/v1/topics/breakout/{topic_id}/story")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.upriver.ai/v1/topics/breakout/{topic_id}/story")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"seed_topic": {
"topic_id": "<string>",
"topic_name": "<string>",
"canonical_name": "<string>",
"vertical": "<string>",
"status": "<string>",
"peak_score": 123,
"discovered_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"category": "<string>",
"score": 123,
"relevance_score": 123,
"engagement": {
"percentile_score": 123
},
"confidence_score": 123,
"last_signal_at": "2023-11-07T05:31:56Z",
"source_summary": {},
"citations": [
{
"source_category": "<string>",
"source_url": "<string>",
"title": "<string>",
"display": "",
"snippet": "<string>",
"source_authority": 123,
"engagement_score": 123,
"published_at": "2023-11-07T05:31:56Z"
}
],
"entities": [
{
"canonical_name": "<string>",
"entity_type": "<string>",
"confidence": 123,
"entity_id": "<string>",
"entity_subtype": "<string>"
}
],
"trend": {
"momentum": 1
},
"citation_rate": [
{
"day": "<string>",
"count": 123
}
],
"narrative": {
"narrative_id": "<string>",
"display_name": "<string>",
"member_count": 123,
"arc_summary": [
"<string>"
]
},
"event_start_at": "2023-11-07T05:31:56Z",
"event_end_at": "2023-11-07T05:31:56Z"
},
"surface": {
"story_id": "<string>",
"member_topic_ids": [
"<string>"
],
"display_name": "<string>",
"story_score": 123,
"member_count": 123,
"lead_topic_id": "<string>",
"description": "<string>",
"latest_signal_at": "2023-11-07T05:31:56Z",
"coherence_score": 123,
"projection_refreshed_at": "2023-11-07T05:31:56Z"
},
"member_topics": [
{
"topic_id": "<string>",
"topic_name": "<string>",
"canonical_name": "<string>",
"vertical": "<string>",
"status": "<string>",
"peak_score": 123,
"discovered_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"category": "<string>",
"score": 123,
"relevance_score": 123,
"engagement": {
"percentile_score": 123
},
"confidence_score": 123,
"last_signal_at": "2023-11-07T05:31:56Z",
"source_summary": {},
"citations": [
{
"source_category": "<string>",
"source_url": "<string>",
"title": "<string>",
"display": "",
"snippet": "<string>",
"source_authority": 123,
"engagement_score": 123,
"published_at": "2023-11-07T05:31:56Z"
}
],
"entities": [
{
"canonical_name": "<string>",
"entity_type": "<string>",
"confidence": 123,
"entity_id": "<string>",
"entity_subtype": "<string>"
}
],
"trend": {
"momentum": 1
},
"citation_rate": [
{
"day": "<string>",
"count": 123
}
],
"narrative": {
"narrative_id": "<string>",
"display_name": "<string>",
"member_count": 123,
"arc_summary": [
"<string>"
]
},
"event_start_at": "2023-11-07T05:31:56Z",
"event_end_at": "2023-11-07T05:31:56Z"
}
],
"search_match": {
"matched_topic_count": 123,
"matched_topic_ids": [
"<string>"
],
"match_sources": [
"<string>"
]
}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}