Skip to content
UpriverUpriverUpriver API Docs

List trends, topics, and breakouts (Beta)

v1.0.0
OpenAPI 3.1.0

Upriver API

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.

Server:https://api.upriver.ai

Production API server

Client Libraries
Shell Curl

List trends, topics, and breakouts (Beta)

​
Query Parameters
  • card_type
    Type: string · Card Typeenumnullable
    values
    • trend_moment
    • topic
    • entity_breakout
  • lifecycle
    Type: string · Lifecyclenullable

    Filter by lifecycle state (e.g. rising).

  • program
    const:  
    general_market

    Production market catalog.

  • persona
    Type: string · Personanullable

    Filter to cards serving this audience persona key.

  • entity
    Type: string · Entitynullable

    Filter to cards featuring this brand, retailer, or product.

  • brand_safety
    Type: string · Brand Safetynullable

    Filter by brand-safety assessment (e.g. safe).

  • platform
    Type: string · Platformnullable

    Filter by source platform (e.g. tiktok).

  • min_size
    Type: integer · Min Size
    min:  
    1    nullable

    Minimum number of videos on the item.

  • since
    Type: string · SinceFormat: date-timenullable

    Only items refreshed at or after this time.

  • sort
    Type: string · Sortenum

    Ranking mode. Rising orders items accelerating relative to their own recent baseline. The legacy momentum value remains accepted.

    values
    • rising
    • momentum
    • newest
    • value
    • freshness
    • size
  • limit
    Type: integer · Limit
    min:  
    1
    max:  
    100

    Integer numbers.

  • offset
    Type: integer · Offset
    min:  
    0

    Pagination offset.

Responses
  • application/json
  • application/json
Request Example for get/v2/radar
curl https://api.upriver.ai/v2/radar \
  --header 'X-API-Key: YOUR_SECRET_TOKEN'

{
  "beta": "Beta: response shapes may change and this surface may converge with /v2/trends.",
  "items": [
    {
      "id": "string",
      "type": "trend_moment",
      "name": "string",
      "description": "string",
      "insight": "string",
      "how_to_act": "string",
      "brand_safety": "string",
      "lifecycle_state": "string",
      "momentum_ratio": 1,
      "value_score": 1,
      "stats": {
        "additionalProperty": "anything"
      },
      "personas": [
        {
          "additionalProperty": "anything"
        }
      ],
      "program": "string",
      "first_seen": "2026-11-06T03:35:49.599Z",
      "last_updated": "2026-11-06T03:35:49.599Z",
      "archived": false
    }
  ],
  "total": 1
}

Successful Response