Skip to main content
POST
/
v2
/
trends
/
broad
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>",
      "trend_type": "theme",
      "has_signature_sound": true,
      "participation_type": "<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.

​
scope
ScopeConfig · object

Time period to search.

​
response_config
TrendsBroadResponseConfig · object

How to format the response.

​
cursor
string | null

Pagination cursor from the previous response's next_cursor field.

​
trend_ids
string[] | null

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

​
trend_type
string[] | null

Filter by trend type(s): "sound", "challenge", "template", "theme". Accepts a single string or a list. Legacy aliases "format" and "other" are also accepted.

​
has_signature_sound
boolean | null

Whether the trend has a specific recognizable audio clip. Independent of trend_type — theme trends can have signature sounds.

​
participation_type
string[] | null

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

​
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 via websearch_to_tsquery.

​
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 (JSONB containment match)

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

​
trends
BroadTrend · object[]
required

List of broad cultural trends currently trending across platforms.

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