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

# Trend Details

> Get a specific trend by its id. Use the /trends/{id}/playback endpoint to get a refreshed audio playback URL.



## OpenAPI

````yaml /api-reference/openapi.json get /v2/trends/{trend_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:
  /v2/trends/{trend_id}:
    get:
      tags:
        - Trends
      summary: Trend Details
      description: >-
        Get a specific trend by its id. Use the /trends/{id}/playback endpoint
        to get a refreshed audio playback URL.
      operationId: get_trend_by_id_v2
      parameters:
        - name: trend_id
          in: path
          required: true
          schema:
            type: string
            title: Trend Id
      responses:
        '200':
          description: Trend details with title, summary, samples, and timeliness.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrendDetailResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    TrendDetailResponse:
      properties:
        id:
          type: string
          title: Id
          description: Stable trend identifier
        title:
          type: string
          title: Title
          description: Short name of the trend
        summary:
          type: string
          title: Summary
          description: 1-3 sentences describing the trend
        uses_specific_sound:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Uses Specific Sound
          description: >-
            Whether the trend uses a specific recognizable sound, derived from
            dominant-sound evidence and signature-sound classification.
        instructions:
          anyOf:
            - type: string
            - type: 'null'
          title: Instructions
          description: Actionable guidance on how to participate in the trend
        status:
          anyOf:
            - type: string
            - type: 'null'
          title: Status
          description: Trend status (e.g., active)
        video_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Video Count
          description: Number of video media items
        audio_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Audio Count
          description: Number of audio media items
        variants_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Variants Count
          description: Number of known variant strings
        video_samples:
          anyOf:
            - items: {}
              type: array
            - type: 'null'
          title: Video Samples
          description: Representative video samples (shape varies by metadata_mode)
        audio_samples:
          anyOf:
            - items: {}
              type: array
            - type: 'null'
          title: Audio Samples
          description: Representative audio samples (shape varies by metadata_mode)
        playback:
          anyOf:
            - type: string
            - type: 'null'
          title: Playback
          description: >-
            Playback URL for the trend's audio (only when requested and
            available)
        freshness_score:
          anyOf:
            - type: number
            - type: 'null'
          title: Freshness Score
          description: Freshness score (0-1)
        tags:
          anyOf:
            - items:
                $ref: '#/components/schemas/TrendTag'
              type: array
            - type: 'null'
          title: Tags
          description: Tags associated with this trend
        sound_category:
          anyOf:
            - type: string
            - type: 'null'
          title: Sound Category
          description: 'Sound type: "music", "speech", "sound_effect", or "mixed"'
        sound_genre:
          anyOf:
            - type: string
            - type: 'null'
          title: Sound Genre
          description: Primary music genre (e.g. pop, hip_hop, electronic)
        sound_subgenre:
          anyOf:
            - type: string
            - type: 'null'
          title: Sound Subgenre
          description: More specific genre classification
        sound_mood:
          anyOf:
            - type: string
            - type: 'null'
          title: Sound Mood
          description: Emotional tone (e.g. happy, sad, energetic, chill)
        sound_energy:
          anyOf:
            - type: string
            - type: 'null'
          title: Sound Energy
          description: 'Energy level: "calm", "low", "moderate", "high", or "intense"'
        sound_tempo_bpm:
          anyOf:
            - type: integer
            - type: 'null'
          title: Sound Tempo Bpm
          description: Tempo in beats per minute
        brand_safety:
          anyOf:
            - type: string
            - type: 'null'
          title: Brand Safety
          description: 'Brand safety rating: "safe", "caution", or "unsafe"'
        brand_safety_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Brand Safety Reason
          description: Explanation for the brand safety rating
        is_song:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Song
          description: Whether the audio is a song (vs. spoken word, sound effect)
        is_catchphrase:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Catchphrase
          description: Whether the trend is built around a repeatable phrase
        catchphrase_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Catchphrase Text
          description: The catchphrase text, when applicable
        has_vocals:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Has Vocals
          description: Whether the audio contains vocals
        has_lyrics:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Has Lyrics
          description: Whether the audio contains sung or rapped lyrics
        detected_language:
          anyOf:
            - type: string
            - type: 'null'
          title: Detected Language
          description: Detected language of the audio content
        participation_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Participation Type
          description: 'What the trend requires: open, timed, lip_sync, choreography'
        content_structure:
          anyOf:
            - type: string
            - type: 'null'
          title: Content Structure
          description: 'Shared visual pattern: none, loose, or structured'
        has_text_template:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Has Text Template
          description: Whether videos share a repeatable text overlay pattern
        text_template_description:
          anyOf:
            - type: string
            - type: 'null'
          title: Text Template Description
          description: Description of the text template format
        topic_scope:
          anyOf:
            - type: string
            - type: 'null'
          title: Topic Scope
          description: >-
            How transferable: universal, vertical, internet_culture,
            event_specific, person_specific
        content_scenarios:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Content Scenarios
          description: Observed content scenarios from video analysis
        sound_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Sound Id
          description: Identifier for the trend's primary sound
        sound_title:
          anyOf:
            - type: string
            - type: 'null'
          title: Sound Title
          description: Title of the trend's primary sound
        sound_artist:
          anyOf:
            - type: string
            - type: 'null'
          title: Sound Artist
          description: Artist of the trend's primary sound
        commercial_music_approved:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Commercial Music Approved
          description: >-
            Whether the platform explicitly marked the sound as approved for
            commercial/business use. Omitted when unknown.
        audio_summary:
          anyOf:
            - type: string
            - type: 'null'
          title: Audio Summary
          description: Brief description of the audio content
        lyric_snippet:
          anyOf:
            - type: string
            - type: 'null'
          title: Lyric Snippet
          description: Short excerpt of lyrics, when available
        lyric_theme:
          anyOf:
            - type: string
            - type: 'null'
          title: Lyric Theme
          description: Thematic summary of the lyrics
        key_instruments:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Key Instruments
          description: Prominent instruments heard in the audio
        emerged_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Emerged At
          description: >-
            Timestamp when the trend first showed enough activity to be
            considered emerging. Drives the ordering of the 'emerging' sort
            mode.
      type: object
      required:
        - id
        - title
        - summary
      title: TrendDetailResponse
      description: >-
        Response for GET /trends/{id}. Only includes fields returned by the
        endpoint.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TrendTag:
      properties:
        tag_name:
          type: string
          title: Tag Name
          description: Tag label (e.g. 'Beauty', 'Comedy')
        strength:
          anyOf:
            - type: number
            - type: 'null'
          title: Strength
          description: Relevance strength of this tag (0-1)
        purpose:
          anyOf:
            - type: string
            - type: 'null'
          title: Purpose
          description: Why this tag applies to the trend
        rationale:
          anyOf:
            - type: string
            - type: 'null'
          title: Rationale
          description: Supporting rationale for the tag assignment
      type: object
      required:
        - tag_name
      title: TrendTag
      description: A tag attached to a trend (e.g., 'Beauty', 'Comedy').
    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
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key

````