Skip to content
UpriverUpriverUpriver API Docs

Guides

Explore Trends Radar

List and search beta radar items across trends, topics, and breakouts

Trends Radar groups cultural activity into three item types: participatory trend moments, durable topics, and breakouts for products or brands gaining attention. Use the /v2/radar endpoints to browse them, inspect one item, or search with a natural-language query.

Before you start

You need an Upriver API key. Send it in the X-API-Key header on every request. The examples below use https://api.upriver.ai and an environment variable named UPRIVER_API_KEY.

Browse radar items

Start with the combined list. It defaults to the general_market catalog, orders by rising, and returns up to 25 items. Use limit and offset to page through results; total counts all items matching your filters.

Terminal window
curl --fail-with-body --get 'https://api.upriver.ai/v2/radar' \
  --header "X-API-Key: $UPRIVER_API_KEY" \
  --data-urlencode 'sort=rising' \
  --data-urlencode 'limit=10' \
  --data-urlencode 'offset=0'

A successful response has this shape:

{
  "beta": "Beta: response shapes may change and this surface may converge with /v2/trends.",
  "items": [
    {
      "id": "item-id",
      "type": "topic",
      "name": "Example topic",
      "description": "A short description of the topic",
      "stats": {"size": 120},
      "archived": false
    }
  ],
  "total": 1
}

The response above is illustrative. Optional fields, including stats, may be null, and the contents of stats vary by item.

For one type at a time, use these list endpoints. They accept the same list filters as /v2/radar, except card_type:

Endpoint Returns
GET /v2/radar/trends Participatory trend moments (trend_moment)
GET /v2/radar/topics Durable topics (topic)
GET /v2/radar/breakouts Product and brand breakouts (entity_breakout)

Choose filters and sort order

Call GET /v2/radar/facets to discover valid values for lifecycle, persona, and brand_safety. These filters use exact values. The combined list also accepts card_type; all list endpoints accept entity, platform, min_size, since, sort, limit, and offset. since is an ISO 8601 timestamp and keeps items refreshed at or after that time.

Terminal window
curl --fail-with-body 'https://api.upriver.ai/v2/radar/facets' \
  --header "X-API-Key: $UPRIVER_API_KEY"

The available list sort values are rising, newest, value, freshness, and size. The legacy momentum value is also accepted and uses the same ordering as rising.

Use an item’s id with GET /v2/radar/items/{item_id} to fetch it with live stats and a stats.traction history. To find relevant items by description, send a query of 2 to 500 characters to POST /v2/radar/search:

Terminal window
curl --fail-with-body 'https://api.upriver.ai/v2/radar/search' \
  --header "X-API-Key: $UPRIVER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"query":"low-waste home projects","limit":10}'

Search returns results, each containing an item and match_score. You can also filter search by card_type, program, lifecycle, and brand_safety.

If a request fails

  • 401: Check that X-API-Key contains an active key.
  • 404 on item detail: The item ID is unavailable.
  • 422: Check parameter types and limits. For example, list limit is 1–100 and search limit is 1–50.
  • 429: Your key has reached its Radar request quota. Limits depend on your plan; contact Upriver support if you need more capacity.
  • 503 on search: Search is temporarily unavailable; retry later.