> For the complete documentation index, see [llms.txt](https://mcp-docs.nichefire.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mcp-docs.nichefire.com/tools/insights-api/list-trends.md).

# List Trends

List the trends stored under a specific topic.

### `list_trends`

### What it does

Lists the trends under a topic as paginated summaries, with optional filters for date range, status, and sort order.

This reads your organization's own saved data, not the public web.

### When to use it

* To browse what a topic has detected, with names and dates rather than bare IDs.
* To narrow by time — what appeared in a given month or quarter.
* To separate what is currently running (`active`) from what has been retired (`stopped`).

Use this rather than [`get_trend_topic`](/tools/insights-api/get-trend-topic.md) whenever you need readable results or filtering; [`get_trend_topic`](/tools/insights-api/get-trend-topic.md) returns IDs only.

### Parameters

| Parameter   | Required | Description                                                                             |
| ----------- | -------- | --------------------------------------------------------------------------------------- |
| `topic_id`  | Yes      | The topic's UUID, from [`list_trend_topics`](/tools/insights-api/list-trend-topics.md). |
| `page`      | No       | Page number, starting at 1.                                                             |
| `limit`     | No       | Items per page, 1–20.                                                                   |
| `date_from` | No       | Start of the date range, `YYYY-MM-DD`.                                                  |
| `date_to`   | No       | End of the date range, `YYYY-MM-DD`.                                                    |
| `order`     | No       | `asc` or `desc` (most recent first).                                                    |
| `status`    | No       | `active` or `stopped`.                                                                  |

The date range applies to the date that matches the status: when filtering by `active`, it filters on when trends were activated; by `stopped`, on when they were stopped.

### Cost

Free. Insights tools do not consume the shared search quota, only a per-key rate limit applies.

[Quota](/errors-and-limits/quota.md)

### Example request

```json
{
  "topic_id": "bf09eef2-e86f-430f-84d2-a71aab335d46",
  "status": "active",
  "date_from": "2026-01-01",
  "order": "desc",
  "limit": 10
}
```

### Example response

```json
{
  "page": 1,
  "limit": 10,
  "total_count": 3,
  "results": [
    {
      "trend_id": "3f7c2a10-58d6-4c91-b0a4-1e93f7d25c88",
      "trend_name": "Ready-to-drink cold brew in convenience retail",
      "status": "active",
      "activated_at": "2026-06-14T00:00:00Z",
      "stopped_at": null
    },
    {
      "trend_id": "a2b6e441-7c03-4f8d-91ba-6d5c0e17f234",
      "trend_name": "Nitro taps in independent cafés",
      "status": "active",
      "activated_at": "2026-05-02T00:00:00Z",
      "stopped_at": null
    }
  ]
}
```

#### Reading the payload

| Field                    | What it holds                                                                              |
| ------------------------ | ------------------------------------------------------------------------------------------ |
| `page`, `limit`          | The page you requested.                                                                    |
| `total_count`            | Total trends matching your filters, across all pages.                                      |
| `results[].trend_id`     | The trend ID — pass it to [`get_trend`](/tools/insights-api/get-trend.md) for full detail. |
| `results[].trend_name`   | The trend, stated as a short name.                                                         |
| `results[].status`       | `active` or `stopped`.                                                                     |
| `results[].activated_at` | When the trend was first detected as active.                                               |
| `results[].stopped_at`   | When it stopped, or `null` if it is still running.                                         |

Note that `total_count` reflects your filters, not the topic as a whole — narrowing by status or date changes it.

This is a summary view. For themes, keywords, sentiment, trajectory, and volume, open a trend with [`get_trend`](/tools/insights-api/get-trend.md).