Skip to main content
POST
/
v2
/
trends
/
broad
Overview
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>",
      "origin": "<string>",
      "virality_reason": "<string>",
      "notability_for_ads": "<string>",
      "trend_type": "theme",
      "has_signature_sound": true,
      "has_visual_template": true,
      "has_choreography": true,
      "id": "<string>",
      "instructions": "<string>",
      "trend_id": "<string>",
      "discovered_at": "<string>",
      "fingerprint": "<string>",
      "canonical_id": "<string>",
      "status": "<string>",
      "metadata": {},
      "variants": [
        "<string>"
      ],
      "all_records": [
        {}
      ],
      "relations_out": [
        {}
      ],
      "relations_in": [
        {}
      ],
      "source_count": 123,
      "video_count": 123,
      "audio_count": 123,
      "variants_count": 123,
      "source_sample": [
        "<unknown>"
      ],
      "video_samples": [
        "<unknown>"
      ],
      "audio_samples": [
        "<unknown>"
      ],
      "playback": "<string>",
      "is_evergreen": true,
      "evergreen_reason": "<string>",
      "evergreen_confidence": 123,
      "source_first_published_at": "<string>",
      "source_last_published_at": "<string>",
      "media_last_published_at": "<string>",
      "earliest_video_at": "<string>",
      "median_video_at": "<string>",
      "video_date_span_days": 123,
      "video_date_count": 123,
      "freshness_date": "<string>",
      "freshness_score": 123,
      "timeliness_status": "<string>",
      "typical_duration_seconds": 123,
      "editorial_date": "<string>",
      "editorial_date_precision": "<string>",
      "activated_at": "<string>",
      "updated_at": "<string>",
      "tags": [
        {
          "tag_name": "<string>",
          "strength": 123,
          "purpose": "<string>",
          "rationale": "<string>"
        }
      ],
      "sound_category": "<string>",
      "sound_genre": "<string>",
      "sound_subgenre": "<string>",
      "sound_mood": "<string>",
      "sound_energy": "<string>",
      "sound_tempo_bpm": 123,
      "sound_tempo_feel": "<string>",
      "brand_safety": "<string>",
      "brand_safety_reason": "<string>",
      "is_song": true,
      "is_catchphrase": true,
      "catchphrase_text": "<string>",
      "has_vocals": true,
      "has_lyrics": true,
      "detected_language": "<string>",
      "sound_usage_type": "<string>",
      "sound_id": "<string>",
      "sound_title": "<string>",
      "sound_artist": "<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_type
string | null

Filter by trend type: "sound", "challenge", "template", "theme". Legacy aliases "format" and "other" are also accepted.

​
has_signature_sound
boolean | null

Filter for trends with a specific, recognizable audio clip

​
has_visual_template
boolean | null

Filter for trends with a recognizable visual structure

​
has_choreography
boolean | null

Filter for trends involving choreographed movement or dance

​
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
​
sound_usage_type
string | null

Filter by how creators use the sound: background_audio, challenge, lip_sync, dance, storytelling, transition

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.