> ## 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. # List Breakout Topics > 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. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/topics/breakout 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: get: tags: - Breakout Topics summary: List Breakout Topics description: >- 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. operationId: list_breakout_topics parameters: - name: vertical in: query required: false schema: anyOf: - type: string - type: 'null' description: 'Filter by vertical: ''sports'', ''tech'', or ''politics''' title: Vertical description: 'Filter by vertical: ''sports'', ''tech'', or ''politics''' - name: category in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Filter by category within the sports vertical (topic mode only), e.g. 'nba' or 'nfl' title: Category description: >- Filter by category within the sports vertical (topic mode only), e.g. 'nba' or 'nfl' - name: status in: query required: false schema: $ref: '#/components/schemas/TopicStatusFilter' description: >- Filter by topic status. Options: 'active' (default), 'detected', 'emerging', 'trending', 'declining', or 'all'. default: active description: >- Filter by topic status. Options: 'active' (default), 'detected', 'emerging', 'trending', 'declining', or 'all'. - name: temporal_status in: query required: false schema: anyOf: - $ref: '#/components/schemas/TemporalStatusFilter' - type: 'null' description: >- 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. title: Temporal Status description: >- 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. - name: min_importance in: query required: false schema: anyOf: - type: number - type: 'null' title: Min Importance - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 title: Limit description: >- Maximum number of results. Requesting more than 20 results requires a credits-based plan. default: 20 description: >- Maximum number of results. Requesting more than 20 results requires a credits-based plan. - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' title: Cursor - name: include in: query required: false schema: type: array items: type: string enum: - citations - entities description: >- Optional expansions to include in the response. Allowed values: citations, entities. Example: include=citations&include=entities default: [] title: Include description: >- Optional expansions to include in the response. Allowed values: citations, entities. Example: include=citations&include=entities - name: citation_sources in: query required: false schema: anyOf: - items: $ref: '#/components/schemas/CitationSourceCategory' type: array - type: 'null' title: Citation Sources description: >- Restrict returned citations to these source categories (news, reddit, twitter). Omit for all sources. Only applies when surface_mode=topic. description: >- Restrict returned citations to these source categories (news, reddit, twitter). Omit for all sources. Only applies when surface_mode=topic. - name: sort_by in: query required: false schema: type: string description: >- 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. default: recommended title: Sort By description: >- 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. - name: discovered_within_hours in: query required: false schema: anyOf: - type: integer maximum: 8760 minimum: 1 - type: 'null' description: >- Keep only topics first seen within this many hours (the 'brand new' filter). Combine with any sort. Omit for no limit. title: Discovered Within Hours description: >- Keep only topics first seen within this many hours (the 'brand new' filter). Combine with any sort. Omit for no limit. - name: surface_mode in: query required: false schema: $ref: '#/components/schemas/ListSurfaceMode' description: List raw topics or deduped derived story surfaces default: topic description: List raw topics or deduped derived story surfaces responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ListTopicsResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: TopicStatusFilter: type: string enum: - active - all - detected - emerging - trending - declining title: TopicStatusFilter description: >- 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. TemporalStatusFilter: type: string enum: - upcoming - ongoing - past title: TemporalStatusFilter description: >- Filter a topic by its request-time event temporal status. Only topics linked to a scheduled event carry a temporal status, so filtering by any of these values implicitly restricts results to event-linked topics. CitationSourceCategory: type: string enum: - news - reddit - twitter title: CitationSourceCategory description: >- 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. ListSurfaceMode: type: string enum: - topic - story title: ListSurfaceMode description: List surface mode for breakout browse responses. ListTopicsResponse: properties: surface_mode: $ref: '#/components/schemas/ListSurfaceMode' description: Whether the list contains raw topics or derived story surfaces default: topic topics: items: $ref: '#/components/schemas/BreakoutTopicResponse' type: array title: Topics description: List of topics when surface_mode=topic stories: items: $ref: '#/components/schemas/TopicStoryViewResponse' type: array title: Stories description: Derived story surfaces when surface_mode=story story_source: anyOf: - $ref: '#/components/schemas/StoryListSource' - type: 'null' description: >- Actual story list source when surface_mode=story. 'projection' means cached group membership with live ranking, 'live' means request-time seed expansion. total_count: type: integer title: Total Count description: >- Total matching rows for the current list mode. When surface_mode=story, this counts exact-deduped projected story surfaces before list-level overlap suppression and pagination. source_topic_count: anyOf: - type: integer - type: 'null' title: Source Topic Count description: >- Raw source-topic seed count behind story mode before exact projection dedupe. This helps distinguish story-surface volume from the broader seed pool used to build them. returned_story_count: anyOf: - type: integer - type: 'null' title: Returned Story Count description: Number of returned story surfaces when surface_mode=story next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: Cursor for next page, if more results type: object required: - total_count title: ListTopicsResponse description: Response for listing breakout topics. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError 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. 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. StoryListSource: type: string enum: - auto - live - projection title: StoryListSource description: How story-mode list surfaces were sourced. 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. StoryViewKind: type: string enum: - cluster - story - timeline title: StoryViewKind description: Requested derived view flavor. 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. TrendDirection: type: string enum: - up - flat - down title: TrendDirection description: Trend direction indicator based on momentum ratio. StorySurfaceType: type: string enum: - topic - cluster - timeline title: StorySurfaceType description: Surface type returned by the derived story view builder. securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-Key ````