> ## Documentation Index > Fetch the complete documentation index at: https://docs.upriver.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get Topic Story View > Get the best available derived story surface around a seed topic. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/topics/breakout/{topic_id}/story openapi: 3.1.0 info: title: Upriver API description: >- 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. version: 1.0.0 servers: - url: https://api.upriver.ai description: Production API server security: [] tags: - name: Brands - name: Products - name: Creators - name: Audience - name: Sponsorships - name: Trends - name: Breakout Topics - name: Taxonomy paths: /v1/topics/breakout/{topic_id}/story: get: tags: - Breakout Topics summary: Get Topic Story View description: Get the best available derived story surface around a seed topic. operationId: get_breakout_topic_story_view parameters: - name: topic_id in: path required: true schema: type: string description: >- Breakout topic UUID returned by `GET /v1/topics/breakout` or `POST /v1/topics/breakout/search`. Do not pass raw query text or domains. title: Topic Id description: >- Breakout topic UUID returned by `GET /v1/topics/breakout` or `POST /v1/topics/breakout/search`. Do not pass raw query text or domains. - name: include in: query required: false schema: type: array items: type: string enum: - citations - entities description: >- Optional related data to include. Allowed: "citations", "entities". default: [] title: Include description: 'Optional related data to include. Allowed: "citations", "entities".' - name: include_citations in: query required: false schema: type: boolean description: 'Deprecated: use include=["citations","entities"] instead.' deprecated: true default: false title: Include Citations description: 'Deprecated: use include=["citations","entities"] instead.' deprecated: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/TopicStoryViewResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: TopicStoryViewResponse: properties: requested_view: $ref: '#/components/schemas/StoryViewKind' description: Requested derived view seed_topic: $ref: '#/components/schemas/BreakoutTopicResponse' description: Seed topic surface: $ref: '#/components/schemas/StorySurfaceResponse' description: Resolved story surface member_topics: items: $ref: '#/components/schemas/BreakoutTopicResponse' type: array title: Member Topics description: Hydrated member topics in surface order search_match: anyOf: - $ref: '#/components/schemas/StorySearchMatchResponse' - type: 'null' description: Search-only metadata explaining why this story matched type: object required: - requested_view - seed_topic - surface title: TopicStoryViewResponse description: Response for a cluster/timeline/story surface seeded by one topic. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError StoryViewKind: type: string enum: - cluster - story - timeline title: StoryViewKind description: Requested derived view flavor. BreakoutTopicResponse: properties: topic_id: type: string title: Topic Id description: >- Topic UUID. Reuse this value with the breakout detail, story-view, and similar-topics endpoints. topic_name: type: string title: Topic Name description: Primary name for the topic canonical_name: type: string title: Canonical Name description: 'Deprecated: use topic_name instead. Primary name for the topic.' deprecated: true vertical: type: string title: Vertical description: 'Vertical: sports, tech, politics' category: anyOf: - type: string - type: 'null' title: Category description: >- Category value on the topic. Filtering by category is only supported for sports topics. status: type: string title: Status description: 'Lifecycle status: detected, emerging, trending, declining' score: anyOf: - type: number - type: 'null' title: Score description: >- Primary ranking score (0-1). Time-decayed composite of source authority, signal velocity, cross-platform confirmation, and engagement quality. Use this for sorting results. relevance_score: anyOf: - type: number - type: 'null' title: Relevance Score description: >- Query match confidence (0-1) when a search query is provided. Higher values indicate a stronger match to the query. Null for browse/list results. engagement: anyOf: - $ref: '#/components/schemas/TopicEngagementResponse' - type: 'null' description: Multi-signal engagement scores for query-time weighting peak_score: type: number title: Peak Score description: >- Peak composite importance score (0-1) combining: source authority (domain trust), velocity (signal frequency), volume (total mentions), cross-platform confirmation (source diversity), and engagement quality. This is a frozen/historical metric representing the topic's peak importance—it does not decay over time. Use score for current rankings. confidence_score: anyOf: - type: number - type: 'null' title: Confidence Score description: >- Detection confidence (0-1) based on: cross-platform confirmation (multiple source types), source authority (trusted domains), entity resolution quality (how reliably entities were identified), and deduplication method (exact vs fuzzy matching). discovered_at: type: string format: date-time title: Discovered At description: When the topic was first detected last_signal_at: anyOf: - type: string format: date-time - type: 'null' title: Last Signal At description: >- Latest evidence-backed signal time for this topic. Prefer this over updated_at for user-facing freshness. updated_at: type: string format: date-time title: Updated At description: Last material row mutation timestamp for the topic source_summary: additionalProperties: type: integer type: object title: Source Summary description: 'Signal count by source category: {news: 5, reddit: 12, web: 3}' citations: items: $ref: '#/components/schemas/BreakoutCitationResponse' type: array title: Citations description: Top citations for this topic entities: items: $ref: '#/components/schemas/BreakoutEntityResponse' type: array title: Entities description: Resolved entities mentioned in topic trend: anyOf: - $ref: '#/components/schemas/TopicTrendResponse' - type: 'null' description: Momentum and trend direction signals citation_rate: anyOf: - items: $ref: '#/components/schemas/CitationRateBucket' type: array - type: 'null' title: Citation Rate description: Daily citation counts for charting (detail endpoint only) narrative: anyOf: - $ref: '#/components/schemas/TopicNarrativeContext' - type: 'null' description: Narrative context when collapse_narratives is enabled temporal_status: anyOf: - type: string enum: - upcoming - ongoing - past - type: 'null' title: Temporal Status description: >- Whether the event this topic is about is upcoming, ongoing, or already past, relative to the request time. Null when the topic is not tied to a scheduled event. event_start_at: anyOf: - type: string format: date-time - type: 'null' title: Event Start At description: >- Scheduled start time (UTC) of the event this topic is about, if known. event_end_at: anyOf: - type: string format: date-time - type: 'null' title: Event End At description: Scheduled end time (UTC) of the event this topic is about, if known. type: object required: - topic_id - topic_name - canonical_name - vertical - status - peak_score - discovered_at - updated_at title: BreakoutTopicResponse description: Single breakout topic in API response. StorySurfaceResponse: properties: story_id: type: string title: Story Id description: Stable opaque ID for this topic-seeded derived surface surface_type: $ref: '#/components/schemas/StorySurfaceType' description: Resolved surface type member_topic_ids: items: type: string type: array title: Member Topic Ids description: Ordered topic members lead_topic_id: anyOf: - type: string - type: 'null' title: Lead Topic Id description: Current presentation-leading topic display_name: type: string title: Display Name description: Display name for the surface description: anyOf: - type: string - type: 'null' title: Description description: Surface summary story_score: type: number title: Story Score description: Story-level ranking score latest_signal_at: anyOf: - type: string format: date-time - type: 'null' title: Latest Signal At description: Latest signal time across members member_count: type: integer title: Member Count description: Current member count coherence_score: anyOf: - type: number - type: 'null' title: Coherence Score description: How coherent the current member set is projection_refreshed_at: anyOf: - type: string format: date-time - type: 'null' title: Projection Refreshed At description: When the backing projection row was last refreshed, if cached type: object required: - story_id - surface_type - member_topic_ids - display_name - story_score - member_count title: StorySurfaceResponse description: Derived story surface for a topic-seeded view. StorySearchMatchResponse: properties: matched_topic_ids: items: type: string type: array title: Matched Topic Ids description: Matched member topic ids that caused this story result to surface matched_topic_count: type: integer title: Matched Topic Count description: Number of matched member topics represented by this story result match_sources: items: type: string type: array title: Match Sources description: Search lanes that surfaced this story result (e.g. topic, family) type: object required: - matched_topic_count title: StorySearchMatchResponse description: How a story result matched the search query. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError TopicEngagementResponse: properties: percentile_score: anyOf: - type: number - type: 'null' title: Percentile Score description: >- Peak subreddit-relative engagement (0-1). Measures how exceptional the topic's best-performing citation is within its community. 0.9 = top 10% of that subreddit's posts. Useful for finding niche topics that over-perform in their community. type: object title: TopicEngagementResponse description: Engagement scoring signals for a topic. BreakoutCitationResponse: properties: source_category: type: string title: Source Category description: 'Source category: news, web, reddit, tiktok, trends' source_url: type: string title: Source Url description: URL of the source title: anyOf: - type: string - type: 'null' title: Title description: Headline of the source, when it has one (null for posts) display: type: string title: Display description: >- Display-ready label for the source — its headline, or the post text when the source has no headline. Prefer this over title. default: '' snippet: anyOf: - type: string - type: 'null' title: Snippet description: Relevant snippet from the source source_authority: anyOf: - type: number - type: 'null' title: Source Authority description: Authority score of the source (0-1) engagement_score: anyOf: - type: number - type: 'null' title: Engagement Score description: Normalized engagement score (0-1) for this citation published_at: anyOf: - type: string format: date-time - type: 'null' title: Published At description: When the source was published type: object required: - source_category - source_url title: BreakoutCitationResponse description: >- Citation in API response — the full topic-surface shape. Inherits the shared display-facing fields (source_category, source_url, title, display) from ``CitationBase`` and adds the richer fields the topic detail surface shows. BreakoutEntityResponse: properties: canonical_name: type: string title: Canonical Name description: Resolved canonical name entity_id: anyOf: - type: string - type: 'null' title: Entity Id description: Opaque identifier for this entity, if resolved entity_type: type: string title: Entity Type description: 'Coarse type: person, org, loc, event, product, entity' confidence: type: number title: Confidence description: Resolution confidence (0-1) entity_subtype: anyOf: - type: string - type: 'null' title: Entity Subtype description: Fine-grained entity type (e.g., sportsperson, city, company) type: object required: - canonical_name - entity_type - confidence title: BreakoutEntityResponse description: Resolved entity in API response. TopicTrendResponse: properties: momentum: anyOf: - type: number maximum: 2 minimum: 0 - type: 'null' title: Momentum description: >- Activity ratio (0.0-2.0). Compares recent signal rate to baseline. 2.0 = 2x usual activity, 1.0 = normal, 0.5 = half, 0.0 = no recent activity. direction: anyOf: - $ref: '#/components/schemas/TrendDirection' - type: 'null' description: >- Simplified trend indicator derived from momentum. 'up' (>1.3) = accelerating, 'flat' (0.7-1.3) = steady, 'down' (<0.7) = decelerating. type: object title: TopicTrendResponse description: Momentum and trend signals for a topic. CitationRateBucket: properties: day: type: string title: Day description: Date in YYYY-MM-DD format count: type: integer title: Count description: Number of citations published that day type: object required: - day - count title: CitationRateBucket description: A single day's citation count for charting. TopicNarrativeContext: properties: narrative_id: type: string title: Narrative Id description: Narrative UUID display_name: type: string title: Display Name description: Human-readable narrative name member_count: type: integer title: Member Count description: Number of topics in this narrative arc_summary: items: type: string type: array title: Arc Summary description: Names of member topics (up to 3, ordered by discovered_at) type: object required: - narrative_id - display_name - member_count title: TopicNarrativeContext description: Inline narrative context on a topic in the list endpoint. StorySurfaceType: type: string enum: - topic - cluster - timeline title: StorySurfaceType description: Surface type returned by the derived story view builder. TrendDirection: type: string enum: - up - flat - down title: TrendDirection description: Trend direction indicator based on momentum ratio. securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-Key ````