Trends List - Upriver API Docs

POST

/

v2

/

trends

/

broad

Trends List

curl --request POST \
  --url https://api.upriver.ai/v2/trends/broad \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "audience": {
    "location": "United States"
  }
}
'

{
  "meta": {
    "generated_at": "2023-11-07T05:31:56Z",
    "industries": [
      "<string>"
    ],
    "continuation_token": "<string>",
    "counts": {
      "total": 123,
      "by_scope": {
        "general": 0,
        "multi_platform": 0,
        "platform_specific": 0
      }
    },
    "source_filters": {
      "platforms": [
        "<string>"
      ],
      "source_names": [
        "<string>"
      ],
      "source_urls": [
        "<string>"
      ],
      "restriction": "none"
    },
    "debug_info": {
      "duration_ms": 123,
      "candidates_before_filter": 123,
      "applied_filters": [
        {
          "name": "<string>",
          "value": "<unknown>",
          "reason": "<string>"
        }
      ]
    }
  },
  "trends": [
    {
      "title": "<string>",
      "summary": "<string>",
      "uses_specific_sound": true,
      "participation_type": "<string>",
      "content_structure": "<string>",
      "has_text_template": true,
      "id": "<string>",
      "status": "<string>",
      "video_samples": [
        "<unknown>"
      ],
      "freshness_score": 123,
      "timeliness_status": "<string>",
      "typical_duration_seconds": 123,
      "tags": [
        {
          "tag_name": "<string>",
          "strength": 123,
          "purpose": "<string>",
          "rationale": "<string>"
        }
      ],
      "brand_safety": "<string>"
    }
  ],
  "has_more": false,
  "next_cursor": "<string>"
}

Authorizations

X-API-Key

string

header

required

Body

application/json

Payload model for the /trends/broad endpoint.

audience

TrendsBroadTargetAudience · object

Where to look for trends.

Show child attributes

scope

ScopeConfig · object

Time period to search.

Show child attributes

response_config

TrendsBroadResponseConfig · object

How to format the response.

Show child attributes

cursor

string | null

Pagination cursor from the previous response's next_cursor field.

sort_by

enum<string>

default:recommended

Sort order for trend ranking. 'recommended' returns trends sorted by relevance and engagement (default). 'timeliness' prioritizes freshest currently-rising trends. 'newest' prioritizes trends that appear newest on the internet (using best-available first-seen signals).

Available options:

recommended,

timeliness,

newest

trend_ids

string[] | null

Return exactly these trends in the given order. When set, all other filters and ranking are ignored.

uses_specific_sound

boolean | null

Filter for trends that use a specific recognizable sound, derived from dominant-sound evidence and signature-sound classification.

participation_type

string[] | null

Filter by participation type(s): 'open', 'timed', 'lip_sync', 'choreography'. Accepts a single string or a list.

content_structure

enum<string> | null

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

Available options:

none,

loose,

structured

has_text_template

boolean | null

Filter for trends with repeatable text overlay format

topic_scope

string | null

Filter by topic scope: 'universal', 'vertical', 'internet_culture', 'event_specific', 'person_specific'

topic_scope_exclude

string[] | null

Exclude trends matching these topic scopes

tags

string[] | null

Include trends having at least one of these tags

exclude_tags

string[] | null

Exclude trends having any of these tags

min_duration

number | null

Minimum typical duration in seconds. Trends with unknown duration are excluded when set.

Required range: x >= 0

max_duration

number | null

Maximum typical duration in seconds. Trends with unknown duration are excluded when set.

Required range: x >= 0

query

string | null

Full-text search query across trend name, description, sound title, artist, genre, mood, and catchphrase. Supports phrases and OR operators.

genre

string | null

Filter by sound genre (e.g. pop, hip_hop, electronic)

mood

string | null

Filter by sound mood (e.g. happy, sad, energetic, chill)

sound_category

string | null

Filter by sound category: "music", "speech", "sound_effect", "mixed"

has_lyrics

boolean | null

Filter for trends with/without sung or rapped lyrics

is_catchphrase

boolean | null

Filter for trends built around a repeatable phrase

min_bpm

integer | null

Minimum tempo in BPM

Required range: x >= 0

max_bpm

integer | null

Maximum tempo in BPM

Required range: x >= 0

content_scenario

string | null

Filter by observed content scenario

energy

string | null

Filter by energy level: "calm", "low", "moderate", "high", "intense"

is_song

boolean | null

Filter for trends with/without a recognizable song

has_vocals

boolean | null

Filter for trends with/without vocal content

detected_language

string | null

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

string | null

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.

brand_safety

string[] | null

Filter by brand safety level(s): "safe", "caution", "unsafe". Accepts a single string or a list. When omitted, unsafe trends are excluded by default.

Response

JSON object containing broad trends

Broad cultural trend detection results. Identifies current, socially relevant cultural topics that could inspire ad creative.

meta

ResponseMeta · object

required

Provenance and optional diagnostics for this response.

Show child attributes

trends

BroadTrend · object[]

required

List of broad cultural trends currently trending across platforms.

Show child attributes

has_more

boolean

default:false

Whether more trends are available beyond this page.

next_cursor

string | null

Cursor to fetch the next page of trends when has_more is true.

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

⌘I

Trends List

curl --request POST \
  --url https://api.upriver.ai/v2/trends/broad \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "audience": {
    "location": "United States"
  }
}
'

{
  "meta": {
    "generated_at": "2023-11-07T05:31:56Z",
    "industries": [
      "<string>"
    ],
    "continuation_token": "<string>",
    "counts": {
      "total": 123,
      "by_scope": {
        "general": 0,
        "multi_platform": 0,
        "platform_specific": 0
      }
    },
    "source_filters": {
      "platforms": [
        "<string>"
      ],
      "source_names": [
        "<string>"
      ],
      "source_urls": [
        "<string>"
      ],
      "restriction": "none"
    },
    "debug_info": {
      "duration_ms": 123,
      "candidates_before_filter": 123,
      "applied_filters": [
        {
          "name": "<string>",
          "value": "<unknown>",
          "reason": "<string>"
        }
      ]
    }
  },
  "trends": [
    {
      "title": "<string>",
      "summary": "<string>",
      "uses_specific_sound": true,
      "participation_type": "<string>",
      "content_structure": "<string>",
      "has_text_template": true,
      "id": "<string>",
      "status": "<string>",
      "video_samples": [
        "<unknown>"
      ],
      "freshness_score": 123,
      "timeliness_status": "<string>",
      "typical_duration_seconds": 123,
      "tags": [
        {
          "tag_name": "<string>",
          "strength": 123,
          "purpose": "<string>",
          "rationale": "<string>"
        }
      ],
      "brand_safety": "<string>"
    }
  ],
  "has_more": false,
  "next_cursor": "<string>"
}