Skip to content
UpriverUpriverUpriver API Docs

Search the radar by natural language (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

Search the radar by natural language (Beta)

​
Body·RadarSearchInput
required
application/json
  • query
    Type: string · Query
    min length:  
    2
    max length:  
    500
    required

    Natural-language description of the trend, topic, or audience.

  • limit
    Type: integer · Limit
    min:  
    1
    max:  
    50

    Integer numbers.

  • card_type
    Type: string · Card Typeenumnullable

    Restrict results to one item type.

    values
    • trend_moment
    • topic
    • entity_breakout
  • program
    const:  
    general_market

    Production market catalog searched for results.

  • lifecycle
    Type: string · Lifecyclenullable

    Restrict results to one lifecycle state.

  • brand_safety
    Type: string · Brand Safetynullable

    Restrict results by brand-safety assessment.

Responses
  • application/json
  • application/json
Request Example for post/v2/radar/search
curl https://api.upriver.ai/v2/radar/search \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_SECRET_TOKEN' \
  --data '{
  "query": "",
  "limit": 10,
  "card_type": "trend_moment",
  "program": "general_market",
  "lifecycle": "",
  "brand_safety": ""
}'

{
  "beta": "Beta: response shapes may change and this surface may converge with /v2/trends.",
  "results": [
    {
      "item": {
        "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
      },
      "match_score": 1
    }
  ]
}

Successful Response