Skip to main content
POST
/
v1
/
trends
/
search
Search
curl --request POST \
  --url https://api.upriver.ai/v1/trends/search \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "categories": [
    "<string>"
  ],
  "brand_url": "<string>",
  "brand_name": "<string>",
  "search_provider": "exa",
  "trend_type": "<string>",
  "platforms": [
    "<string>"
  ],
  "marketing_goals": [
    "<string>"
  ],
  "limit": 10,
  "category_search_top_k": 5
}
'
{
  "matches": [
    {
      "trend_id": "<string>",
      "trend_name": "<string>",
      "relevance_score": 0.5,
      "reasoning": "<string>",
      "suggested_approach": "<string>",
      "platforms": [
        "<string>"
      ]
    }
  ],
  "summary": "<string>",
  "generated_at": "<string>"
}

Authorizations

​
X-API-Key
string
header
required

Body

application/json

Request body for /v1/trends/search.

​
categories
string[] | null

Category phrases or keywords to target when searching for trends.

​
brand_url
string | null

Brand website URL to auto-classify before searching (mutually exclusive with categories).

​
brand_name
string | null

Optional brand name hint used in prompts.

​
search_provider
string
default:exa

Brand research provider when brand_url is supplied.

​
trend_type
string | null

Filter by trend type (e.g., 'sound' or 'other').

​
platforms
string[] | null

Platforms to prioritize when ranking trends (defaults to TikTok).

​
marketing_goals
string[] | null

Optional marketing goals to guide match selection.

​
limit
integer
default:10

Maximum number of matched trends to return.

Required range: 1 <= x <= 50
​
category_search_top_k
integer
default:5

Number of categories to request when resolving brand_url.

Required range: 1 <= x <= 20

Response

Successful Response

Response for trend search/match.

​
matches
TrendMatch · object[]
required

Matched trends with strategies

​
summary
string
required

Summary of trend opportunities

​
generated_at
string
required

ISO timestamp when analysis was generated