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

# Trends List

> Get the latest trending formats.

Result order is controlled by `sort_by`: `recommended` (balanced default),
`newest` (catalog arrivals), or `rising` (accelerating right now). They answer
different questions; see [Sorting & Ranking](/trends/sorting) for how they
differ, with examples.


## OpenAPI

````yaml post /v2/trends/broad
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/broad:
    post:
      tags:
        - Trends
      summary: Trends List
      description: Get the latest trending formats.
      operationId: trends_broad_v2
      parameters:
        - name: commercial_music_status
          in: query
          required: false
          schema:
            anyOf:
              - const: approved
                type: string
              - type: 'null'
            description: >-
              When set to 'approved', returns only sound trends whose attached
              music was explicitly approved by the platform for
              commercial/business use. Trends without a known approval signal
              are excluded.
            title: Commercial Music Status
          description: >-
            When set to 'approved', returns only sound trends whose attached
            music was explicitly approved by the platform for
            commercial/business use. Trends without a known approval signal are
            excluded.
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
                - $ref: '#/components/schemas/TrendsBroadInput'
                - type: 'null'
              title: Data
      responses:
        '200':
          description: JSON object containing broad trends
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrendsBroadResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    TrendsBroadInput:
      properties:
        audience:
          $ref: '#/components/schemas/TrendsBroadTargetAudience'
        scope:
          $ref: '#/components/schemas/ScopeConfig'
          description: Time period to search.
        response_config:
          $ref: '#/components/schemas/TrendsBroadResponseConfig'
        cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Cursor
          description: Pagination cursor from the previous response's next_cursor field.
        sort_by:
          type: string
          enum:
            - recommended
            - emerging
            - newest
            - rising
          title: Sort By
          description: >-
            Sort order for trend ranking. 'recommended' returns trends sorted by
            relevance and engagement (default). 'emerging' (legacy; prefer
            'newest') surfaces trends that recently crossed from noise to
            signal. 'newest' returns trends by when they were first confirmed as
            real. 'rising' surfaces trends whose posting activity is
            accelerating right now; the signal fades as a trend's latest
            evidence ages. Legacy values 'momentum' and 'timeliness' are
            accepted and resolve to 'rising' and 'newest' respectively. Guide:
            https://docs.upriver.ai/trends/sorting
          default: recommended
        trend_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Trend Ids
          description: >-
            Return exactly these trends in the given order. When set, all other
            filters and ranking are ignored.
        uses_specific_sound:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Uses Specific Sound
          description: >-
            Filter for trends that use a specific recognizable sound, derived
            from dominant-sound evidence and signature-sound classification.
        participation_type:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Participation Type
          description: >-
            Filter by participation type(s): 'open', 'timed', 'lip_sync',
            'choreography'. Accepts a single string or a list.
        content_structure:
          anyOf:
            - type: string
              enum:
                - none
                - loose
                - structured
            - type: 'null'
          title: Content Structure
          description: >-
            Filter by shared non-audio pattern across videos: 'none' (sound-led
            only), 'loose' (shared theme/aesthetic without a repeatable
            template), or 'structured' (repeatable text, editing, or visual
            template).
        has_text_template:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Has Text Template
          description: Filter for trends with repeatable text overlay format
        topic_scope:
          anyOf:
            - type: string
            - type: 'null'
          title: Topic Scope
          description: >-
            Filter by topic scope: 'universal', 'vertical', 'internet_culture',
            'event_specific', 'person_specific'
        topic_scope_exclude:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Topic Scope Exclude
          description: Exclude trends matching these topic scopes
        tags:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Tags
          description: Include trends having at least one of these tags
        exclude_tags:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Exclude Tags
          description: Exclude trends having any of these tags
        min_duration:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Min Duration
          description: >-
            Minimum typical duration in seconds. Trends with unknown duration
            are excluded when set.
        max_duration:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Max Duration
          description: >-
            Maximum typical duration in seconds. Trends with unknown duration
            are excluded when set.
        query:
          anyOf:
            - type: string
            - type: 'null'
          title: Query
          description: >-
            Full-text search query across trend name, description, sound title,
            artist, genre, mood, and catchphrase. Supports phrases and OR
            operators.
        genre:
          anyOf:
            - type: string
            - type: 'null'
          title: Genre
          description: Filter by sound genre (e.g. pop, hip_hop, electronic)
        mood:
          anyOf:
            - type: string
            - type: 'null'
          title: Mood
          description: Filter by sound mood (e.g. happy, sad, energetic, chill)
        sound_category:
          anyOf:
            - type: string
            - type: 'null'
          title: Sound Category
          description: 'Filter by sound category: "music", "speech", "sound_effect", "mixed"'
        has_lyrics:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Has Lyrics
          description: Filter for trends with/without sung or rapped lyrics
        is_catchphrase:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Catchphrase
          description: Filter for trends built around a repeatable phrase
        min_bpm:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Min Bpm
          description: Minimum tempo in BPM
        max_bpm:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Max Bpm
          description: Maximum tempo in BPM
        content_scenario:
          anyOf:
            - type: string
            - type: 'null'
          title: Content Scenario
          description: Filter by observed content scenario
        energy:
          anyOf:
            - type: string
            - type: 'null'
          title: Energy
          description: 'Filter by energy level: "calm", "low", "moderate", "high", "intense"'
        is_song:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Song
          description: Filter for trends with/without a recognizable song
        has_vocals:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Has Vocals
          description: Filter for trends with/without vocal content
        detected_language:
          anyOf:
            - type: string
            - type: 'null'
          title: Detected Language
          description: >-
            Filter by content language — the primary language of captions,
            hashtags, and text overlays (ISO 639-1 code, e.g. "en", "es"). Falls
            back to audio language when content language is unavailable.
        timeliness_status:
          anyOf:
            - type: string
            - type: 'null'
          title: Timeliness Status
          description: >-
            Minimum freshness level. 'recent' (>=0.7), 'active' (>=0.3), 'stale'
            (>=0.1). Filter is 'at least this fresh' -- timeliness_status=active
            returns recent + active trends.
        discovered_within_hours:
          anyOf:
            - type: integer
              maximum: 8760
              minimum: 1
            - type: 'null'
          title: Discovered Within Hours
          description: >-
            Only include trends discovered within the past N hours (e.g. 24 for
            the last day, 168 for the last week).
        brand_safety:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Brand Safety
          description: >-
            Filter by brand safety level(s): "safe", "caution", "unsafe".
            Accepts a single string or a list. When omitted, unsafe trends are
            excluded by default.
      type: object
      title: TrendsBroadInput
      description: Payload model for the /trends/broad endpoint.
      example:
        audience:
          location: United States
    TrendsBroadResponse:
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
          description: Provenance and optional diagnostics for this response.
        trends:
          items:
            $ref: '#/components/schemas/BroadTrend'
          type: array
          title: Trends
          description: List of broad cultural trends currently trending across platforms.
        has_more:
          type: boolean
          title: Has More
          description: Whether more trends are available beyond this page.
          default: false
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
          description: Cursor to fetch the next page of trends when has_more is true.
      type: object
      required:
        - meta
        - trends
      title: TrendsBroadResponse
      description: >-
        Broad cultural trend detection results.

        Identifies current, socially relevant cultural topics that could inspire
        ad creative.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TrendsBroadTargetAudience:
      properties:
        geo:
          items:
            type: string
          type: array
          title: Geo
          description: Which countries to focus on (use ISO country codes like 'US', 'CA')
          default:
            - US
      type: object
      title: TrendsBroadTargetAudience
      description: Where to look for trends.
    ScopeConfig:
      properties:
        from_time:
          anyOf:
            - type: string
            - type: string
              format: date-time
            - type: 'null'
          title: From Time
          description: >-
            The start of the time window for the scan. This can be an absolute
            timestamp in ISO 8601 format (e.g., '2025-08-11T00:00:00Z'), or a
            relative duration string from the current time (e.g., '7d' for 7
            days ago, '24h' for 24 hours ago, '2w' for 2 weeks ago).
          default: 90d
        to_time:
          anyOf:
            - type: string
            - type: string
              format: date-time
            - type: 'null'
          title: To Time
          description: >-
            The end of the time window for the scan. This can be the string
            'now', an absolute timestamp in ISO 8601 format (e.g.,
            '2025-08-11T00:00:00Z'), or a relative duration string from the
            current time (e.g., '24h' for 24 hours ago). A relative duration for
            `to_time` should be more recent than `from_time`.
          default: now
        platforms:
          anyOf:
            - items:
                type: string
                enum:
                  - tiktok
                  - instagram
                  - youtube
                  - twitch
                  - reddit
                  - x
                  - discord
                  - facebook
                  - snapchat
                  - pinterest
                  - forums
                  - blogs
                  - reviews
              type: array
            - type: 'null'
          title: Platforms
          description: >-
            Platforms to scan and include in results (e.g., Reddit, blogs,
            forums)
      type: object
      title: ScopeConfig
      description: |-
        Where/when to look for signals and which platforms to use.
        These are query filters (not brand metadata).

        Time window:
          - Use 'from_time' (start) and 'to_time' (end).
          - Accepts ISO8601 UTC or relative durations like '7d', '24h', '2w'.
          - If only 'from_time' is relative, window is [now - duration, now].
          - 'to_time' may be 'now' (default), ISO8601 UTC, or a relative duration
            interpreted as now - duration.
          - After normalization the service validates start < end.

        Platforms:
          - Use 'platforms' to specify which platforms to both scan AND return
            (e.g., reddit, blogs, forums).
          - This controls both the data sources analyzed and the results returned.
    TrendsBroadResponseConfig:
      properties:
        include_rollup:
          type: boolean
          title: Include Rollup
          description: Include a summary paragraph of all the trends found.
          default: false
        verbosity:
          type: string
          title: Verbosity
          description: 'How much detail to include: compact | standard | verbose.'
          default: standard
        max_results:
          type: integer
          maximum: 50
          minimum: 1
          title: Max Results
          description: Maximum number of trends to return.
          default: 10
        min_confidence:
          type: number
          maximum: 1
          minimum: 0
          title: Min Confidence
          description: Only return trends with confidence above this score.
          default: 0.55
        media_limit:
          anyOf:
            - type: integer
              maximum: 50
              minimum: 1
            - type: 'null'
          title: Media Limit
          description: 'Max media samples per trend. Default: 3 (basic/none), 10 (debug).'
      type: object
      title: TrendsBroadResponseConfig
      description: How to format the response.
    ResponseMeta:
      properties:
        generated_at:
          type: string
          format: date-time
          title: Generated At
          description: UTC timestamp when this response was generated
        industries:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Industries
          description: Resolved industry labels, when applicable
        continuation_token:
          anyOf:
            - type: string
            - type: 'null'
          title: Continuation Token
          description: A token to retrieve the next part of the result (e.g., citations).
        counts:
          anyOf:
            - $ref: '#/components/schemas/ResponseCounts'
            - type: 'null'
          description: Item counts and scope breakdown (basic and debug modes)
        source_filters:
          anyOf:
            - $ref: '#/components/schemas/SourceFilters'
            - type: 'null'
          description: Applied source filters (basic and debug modes)
        debug_info:
          anyOf:
            - $ref: '#/components/schemas/DebugInfo'
            - type: 'null'
          description: Development diagnostics (debug mode only)
      type: object
      required:
        - generated_at
      title: ResponseMeta
      description: |-
        Response-level metadata (flat and endpoint-agnostic).

        Provenance (always present):
          - generated_at, time_window, industries

        Diagnostics (gated by metadata_mode):
          - counts: ResponseCounts          [included when metadata_mode in {'basic','debug'}]
          - source_filters: SourceFilters   [included when metadata_mode in {'basic','debug'}]
          - debug_info: DebugInfo           [included when metadata_mode == 'debug']

        Notes:
          - 'counts.total' SHOULD equal the length of this endpoint's primary items array.
          - 'by_scope' counts are based on ContentScope classification of returned items.
          - ContentScope is about applicability (output classification), not where data
            was sourced.
    BroadTrend:
      properties:
        title:
          type: string
          title: Title
          description: Short name of the trend
        summary:
          type: string
          title: Summary
          description: 1-3 sentences describing why it's culturally relevant
        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.
        participation_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Participation Type
          description: >-
            What the trend requires from creators: open, timed, lip_sync,
            choreography
        content_structure:
          anyOf:
            - type: string
            - type: 'null'
          title: Content Structure
          description: >-
            Shared non-audio pattern across videos: none (sound-led only), loose
            (shared theme/aesthetic without a repeatable template), or
            structured (repeatable text, editing, or visual template).
        has_text_template:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Has Text Template
          description: Whether videos share a repeatable text overlay pattern
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
          description: Stable trend identifier
        status:
          anyOf:
            - type: string
            - type: 'null'
          title: Status
          description: Trend status (e.g., active)
        video_samples:
          anyOf:
            - items: {}
              type: array
            - type: 'null'
          title: Video Samples
          description: Sample of video items [{url, media_key}]
        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.
        freshness_score:
          anyOf:
            - type: number
            - type: 'null'
          title: Freshness Score
          description: Freshness score (0-1) based on most recent evidence date
        timeliness_status:
          anyOf:
            - type: string
            - type: 'null'
          title: Timeliness Status
          description: 'Timeliness status: recent/active/stale/cold'
        typical_duration_seconds:
          anyOf:
            - type: number
            - type: 'null'
          title: Typical Duration Seconds
          description: >-
            Representative content duration in seconds. For sound trends: the
            sound's duration. For other trends: median of video durations.
        tags:
          anyOf:
            - items:
                $ref: '#/components/schemas/TrendTag'
              type: array
            - type: 'null'
          title: Tags
          description: Tags associated with this trend
        brand_safety:
          anyOf:
            - type: string
            - type: 'null'
          title: Brand Safety
        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.
      type: object
      required:
        - title
        - summary
      title: BroadTrend
      description: A single broad cultural trend with social relevance.
    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
    ResponseCounts:
      properties:
        total:
          type: integer
          title: Total
          description: Total number of items in the response (e.g., len(trends)).
        by_scope:
          $ref: '#/components/schemas/ContentScopeCounts'
          description: Breakdown by ContentScope for the returned items.
      type: object
      required:
        - total
        - by_scope
      title: ResponseCounts
      description: >-
        Top-level count diagnostics for the response payload.

        - 'total' MUST equal the number of items returned in this endpoint's
        main list.

        - 'by_scope' breaks down that same set by ContentScope.
    SourceFilters:
      properties:
        platforms:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Platforms
        source_names:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Source Names
        source_urls:
          anyOf:
            - items:
                type: string
                maxLength: 2083
                minLength: 1
                format: uri
              type: array
            - type: 'null'
          title: Source Urls
        restriction:
          type: string
          enum:
            - none
            - prioritize
            - only
          title: Restriction
          default: none
      type: object
      title: SourceFilters
    DebugInfo:
      properties:
        duration_ms:
          type: integer
          title: Duration Ms
          description: End-to-end processing time for this request (ms).
        candidates_before_filter:
          type: integer
          title: Candidates Before Filter
          description: >-
            Number of candidate items BEFORE applying
            min_confidence/max_results.
        applied_filters:
          items:
            $ref: '#/components/schemas/AppliedFilter'
          type: array
          title: Applied Filters
          description: List of filters/normalizations that materially changed the payload.
      type: object
      required:
        - duration_ms
        - candidates_before_filter
      title: DebugInfo
      description: |-
        Optional development diagnostics (included when metadata_mode='debug').
        Times and counts should refer to the current request execution only.
    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').
    ContentScopeCounts:
      properties:
        general:
          type: integer
          title: General
          default: 0
        multi_platform:
          type: integer
          title: Multi Platform
          default: 0
        platform_specific:
          type: integer
          title: Platform Specific
          default: 0
      type: object
      title: ContentScopeCounts
      description: |-
        Count of returned items by ContentScope.
        These counts reflect the final payload after confidence/limit filters.
    AppliedFilter:
      properties:
        name:
          type: string
          title: Name
          description: Filter key, e.g., 'time_range', 'platforms', 'min_confidence'.
        value:
          title: Value
          description: Applied value (JSON-serializable).
        reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Reason
          description: Optional note (e.g., 'filled default', 'normalized').
      type: object
      required:
        - name
        - value
      title: AppliedFilter
      description: >-
        Structured record of a filter or normalization that affected the
        returned payload.

        Good for audit/debug; suitable for 'metadata_mode=debug'.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key

````