> ## 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 Narrative

> Get a narrative by ID with member topics.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/topics/breakout/narratives/{narrative_id}
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/narratives/{narrative_id}:
    get:
      tags:
        - Breakout Topics
      summary: Get Narrative
      description: Get a narrative by ID with member topics.
      operationId: get_narrative
      parameters:
        - name: narrative_id
          in: path
          required: true
          schema:
            type: string
            description: Narrative UUID returned by `GET /v1/topics/breakout/narratives`.
            title: Narrative Id
          description: Narrative UUID returned by `GET /v1/topics/breakout/narratives`.
        - name: include
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
              enum:
                - citations
                - entities
            description: >-
              Optional expansions to include on member topics. Allowed values:
              citations, entities. Example: include=citations&include=entities
            default: []
            title: Include
          description: >-
            Optional expansions to include on member topics. Allowed values:
            citations, entities. Example: include=citations&include=entities
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NarrativeDetailResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    NarrativeDetailResponse:
      properties:
        narrative:
          $ref: '#/components/schemas/NarrativeResponse'
        member_topics:
          items:
            $ref: '#/components/schemas/BreakoutTopicResponse'
          type: array
          title: Member Topics
          description: Topics belonging to this narrative
      type: object
      required:
        - narrative
      title: NarrativeDetailResponse
      description: Narrative with its member topics.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    NarrativeResponse:
      properties:
        narrative_id:
          type: string
          title: Narrative Id
          description: UUID identifier
        slug:
          anyOf:
            - type: string
            - type: 'null'
          title: Slug
          description: URL-friendly slug (non-identity)
        display_name:
          type: string
          title: Display Name
          description: Human-readable name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: Longer description of the developing story
        vertical:
          type: string
          title: Vertical
          description: Vertical slug
        member_count:
          type: integer
          title: Member Count
          description: Number of linked topics
        total_citations:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Citations
          description: Total citations across all member topics
        combined_source_summary:
          anyOf:
            - additionalProperties:
                type: integer
              type: object
            - type: 'null'
          title: Combined Source Summary
          description: Aggregate source counts across members
        date_range:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Date Range
          description: Earliest and latest discovered_at across members
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
        - narrative_id
        - display_name
        - vertical
        - member_count
        - created_at
        - updated_at
      title: NarrativeResponse
      description: A lightweight narrative arc linking related breakout topics.
    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.
    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.
    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

````