> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upriver.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

> [!NOTE]
>
> Trends Radar is in beta. Response shapes may change, and this surface may
> converge with `/v2/trends`. Every successful response includes a `beta` note.

## 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.

```bash theme={null}
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:

```json theme={null}
{
  "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.

```bash theme={null}
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`.

## Inspect or search

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`:

```bash theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.