# Trends MCP API reference

> Trends MCP: the trend data MCP server. Ask Claude, ChatGPT or Cursor whether a topic is growing and get the numbers from search, social, shopping, apps and developer platforms. 54 data sources across 27 platforms, through 5 tools over MCP or a REST API.

Markdown of https://www.trendsmcp.ai/docs. Generated from the API catalog on 2026-11-17.

## Endpoints

- MCP, sign in (Claude, ChatGPT): `https://www.trendsmcp.ai/mcp`. No key to paste.
- MCP, API key (Cursor, VS Code, Claude Code, other clients): `https://api.trendsmcp.ai/mcp`
- REST: `POST https://api.trendsmcp.ai/api` with a JSON body; `mode` picks the tool
- Auth: `Authorization: Bearer YOUR_API_KEY` (the bare key works too). Free key: https://www.trendsmcp.ai/account (email and an 8-digit code, no card)

## Tools

- `get_time_series`: Full history for one topic. About five years of weekly history for one keyword on one source, as a 0 to 100 index plus volume where the source has it. Cost: 1 request per source (data type) in the call; 'all' = every keyword source.
- `get_growth`: How fast something is rising. Point-to-point growth over one or more windows, on one source or several in the same call. Cost: 1 request per source (data type) in the call, every window included; 'all' = every keyword source.
- `get_top_trends`: What's moving right now. A live ranked board with no keyword: the current leaders, or the biggest climbers against an earlier snapshot. Cost: 1 request per 10 rows per board: limit 100 (the default) = 10 requests per board.
- `get_context`: What people are saying. What people are posting, reading and betting about a keyword right now: posts, videos, stories, comments and markets from each source, with engagement. Cost: 1 request per source (data type) in the call; 'all' = every context source.
- `get_reviews`: What customers say. What customers say about a brand, app, product or place: the matched listing with its all-time rating, then the newest reviews from each source with stars, the company's reply and helpful votes. Cost: 1 request per source (data type) in the call; 'all' = every review source.
- `get_usage`: Free. MCP only: your plan, requests used and left, reset date.

### get_time_series

Full history for one topic. About five years of weekly history for one keyword on one source, as a 0 to 100 index plus volume where the source has it.

- Cost: 1 request per source (data type) in the call; 'all' = every keyword source
- MCP tool `get_time_series`; REST `"mode": "get_time_series"`

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `keyword` | string | yes | Format depends on the source. |
| `source` | string | yes | One source, several separated by commas, or 'all'. |

Options some data sources take:

| Option | Works with | Meaning |
|---|---|---|
| `country` | `Google Search`, `Google Images`, `Google News`, `Google Shopping`, `YouTube`, `TikTok`, `Pinterest` | ISO 3166-1 alpha-2 country code (US, GB, JP). Boards, TikTok and review stores default to US; Google time series and growth default to worldwide |
| `language` | `Wikipedia` | Wikipedia language edition (en, de, ja, pt); defaults to en |
| `resolution` | `Google Search`, `Google Images`, `Google News`, `Google Shopping`, `YouTube` | 'weekly' (about 5 years, default) or 'daily' (last 90 days, fetched live) |

Data sources (`source`, 14): `Google Search`, `Google Images`, `Google News`, `Google Shopping`, `YouTube`, `Wikipedia`, `TikTok`, `Amazon`, `Pinterest`, `npm`, `Python`, `Steam`, `App Downloads`, `App Rankings`. Formats and categories: https://www.trendsmcp.ai/data-catalog.md

Request:

```bash
curl -X POST https://api.trendsmcp.ai/api \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"mode": "get_time_series", "keyword": "electric vehicles", "source": "Google Search"}'
```

Response: A list of points, oldest first (weekly for most sources, daily or monthly for some). About 260 weekly points (5 years) per call.

| Field | Type | Meaning |
|---|---|---|
| `date` | string | ISO 8601 date of the point, e.g. 2026-03-21. |
| `value` | number | Interest on a 0 to 100 index. |
| `volume` | number \| null | Absolute volume where the source has it (searches, views, downloads). |
| `keyword` | string | The keyword you asked for. |
| `source` | string | The source used. |

```json
[
  {
    "date": "2026-10-17",
    "value": 47,
    "volume": 25853617,
    "keyword": "bitcoin",
    "source": "google search"
  },
  {
    "date": "2026-10-24",
    "value": 52,
    "volume": 28012440,
    "keyword": "bitcoin",
    "source": "google search"
  }
]
```

### get_growth

How fast something is rising. Point-to-point growth over one or more windows, on one source or several in the same call.

- Cost: 1 request per source (data type) in the call, every window included; 'all' = every keyword source
- MCP tool `get_growth`; REST `"mode": "get_growth"`

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `keyword` | string | yes | Format depends on the source. |
| `source` | string | yes | One source, several separated by commas, or 'all'. |
| `percent_growth` | string[] | no | Window presets such as 3M, 12M or YTD. Default 12M. |

Options some data sources take:

| Option | Works with | Meaning |
|---|---|---|
| `country` | `Google Search`, `Google Images`, `Google News`, `Google Shopping`, `YouTube`, `TikTok`, `Pinterest` | ISO 3166-1 alpha-2 country code (US, GB, JP). Boards, TikTok and review stores default to US; Google time series and growth default to worldwide |
| `language` | `Wikipedia` | Wikipedia language edition (en, de, ja, pt); defaults to en |
| `resolution` | `Google Search`, `Google Images`, `Google News`, `Google Shopping`, `YouTube` | 'weekly' (about 5 years, default) or 'daily' (last 90 days, fetched live) |

Windows: any number with D, W, M or Y up to 5 years, plus MTD, QTD and YTD. Default `12M`. Common: `7D`, `1W`, `14D`, `2W`, `30D`, `1M`, `2M`, `3M`, `6M`, `9M`, `12M`, `1Y`, `18M`, `24M`, `2Y`, `36M`, `3Y`, `48M`, `4Y`, `60M`, `5Y`, `MTD`, `QTD`, `YTD`.

A custom range (REST) is an object in `percent_growth`:

| Field | Type | Meaning |
|---|---|---|
| `name` | string | Optional label, returned as period. |
| `recent` | string | The more recent date, YYYY-MM-DD. |
| `baseline` | string | The date to compare with, YYYY-MM-DD. |

Data sources (`source`, 14): `Google Search`, `Google Images`, `Google News`, `Google Shopping`, `YouTube`, `Wikipedia`, `TikTok`, `Amazon`, `Pinterest`, `npm`, `Python`, `Steam`, `App Downloads`, `App Rankings`. Formats and categories: https://www.trendsmcp.ai/data-catalog.md

Request:

```bash
curl -X POST https://api.trendsmcp.ai/api \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"mode": "get_growth", "keyword": "electric vehicles", "source": "Google Search", "percent_growth": ["3M", "12M"]}'
```

Response: One result per window you asked for.

| Field | Type | Meaning |
|---|---|---|
| `search_term` | string | The keyword you asked for. |
| `data_source` | string | The source used. |
| `results[].period` | string | The window, e.g. 12M, or your custom name. |
| `results[].growth` | number | Change in percent, positive or negative. |
| `results[].direction` | string | increase or decrease. |
| `results[].recent_date / baseline_date` | string | The two dates compared. |
| `results[].recent_value / baseline_value` | number | The 0 to 100 index at those dates. |
| `results[].volume_growth` | number \| null | Change in absolute volume, where the source has volume. |

```json
{
  "search_term": "nike",
  "data_source": "google search",
  "results": [
    {
      "period": "12M",
      "growth": -12.31,
      "direction": "decrease",
      "recent_date": "2026-10-24",
      "baseline_date": "2025-10-25",
      "recent_value": 57,
      "baseline_value": 65,
      "volume_growth": -12.31
    }
  ]
}
```

### get_top_trends

What's moving right now. A live ranked board with no keyword: the current leaders, or the biggest climbers against an earlier snapshot.

- Cost: 1 request per 10 rows per board: limit 100 (the default) = 10 requests per board
- MCP tool `get_top_trends`; REST `"mode": "get_top_trends"`

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `type` | string | yes | One board, several separated by commas, or 'all'. |
| `limit` | integer | no | Rows per board, 1 to 200. Default 100. Each 10 rows cost 1 request. |
| `offset` | integer | no | Rows to skip. Default 0. |
| `sort` | string | no | rank (default) or rank_change for climbers. |
| `window` | string | no | With rank_change: 1d, 3d, 7d, 14d, 30d. Default 30d. |

Options some data sources take:

| Option | Works with | Meaning |
|---|---|---|
| `country` | `Google Trends`, `Google Trends by Category`, `Pinterest Trending`, `Pinterest Trending by Category`, `TikTok Trending Hashtags`, `TikTok Trending Hashtags by Category`, `X (Twitter) Trending`, `YouTube Trending` | ISO 3166-1 alpha-2 country code (US, GB, JP). Boards, TikTok and review stores default to US; Google time series and growth default to worldwide |
| `category` | `Amazon Best Sellers by Category`, `Google Trends by Category`, `Pinterest Trending by Category`, `Top Websites`, `Substack by Category`, `TikTok Trending Hashtags by Category` | Official board name within the feed; without it the feed mixes every board |

Data sources (`type`, 27): `Amazon Best Sellers Top Rated`, `Amazon Best Sellers by Category`, `App Store Top Free`, `App Store Top Paid`, `GitHub`, `Google News Top News`, `Google Play`, `Google Trends`, `Google Trends by Category`, `IMDb MOVIEmeter`, `Open Library Trending Books`, `Pinterest Trending`, `Pinterest Trending by Category`, `Polymarket Top Markets`, `Reddit Hot Posts`, `Reddit World News`, `Top Websites`, `Spotify Top Podcasts`, `Steam Most Played`, `Substack`, `Substack by Category`, `TikTok Trending Hashtags`, `TikTok Trending Hashtags by Category`, `TikTok Trending Searches`, `Wikipedia Trending`, `X (Twitter) Trending`, `YouTube Trending`. Formats and categories: https://www.trendsmcp.ai/data-catalog.md

Request:

```bash
curl -X POST https://api.trendsmcp.ai/api \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"mode": "get_top_trends", "type": "Google Trends", "limit": 10}'
```

Response: The board as of its latest snapshot. Rows are [rank, keyword] (plus the category path on category boards); with sort rank_change they are objects with prev_rank and rank_change.

| Field | Type | Meaning |
|---|---|---|
| `type` | string | The board. |
| `as_of_ts` | string | When the snapshot was taken. |
| `count` | number | Rows returned. |
| `data` | array | [rank, keyword] rows, or {rank, keyword, prev_rank, rank_change} with sort rank_change. |
| `requests_charged` | number | Requests this answer cost: 1 per 10 rows returned (several boards: the sum). |
| `cost_note` | string | How limit sets the cost, and its default. |

```json
{
  "type": "Google Trends",
  "as_of_ts": "2026-10-27T12:00:00Z",
  "count": 3,
  "data": [
    [
      1,
      "world series"
    ],
    [
      2,
      "election polls"
    ],
    [
      3,
      "halloween costumes"
    ]
  ]
}
```

### get_context

What people are saying. What people are posting, reading and betting about a keyword right now: posts, videos, stories, comments and markets from each source, with engagement.

- Cost: 1 request per source (data type) in the call; 'all' = every context source
- MCP tool `get_context`; REST `"mode": "get_context"`

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `keyword` | string | yes | Any name or phrase. |
| `source` | string | yes | One source, several separated by commas, or 'all'. |
| `days` | integer | no | Look back 1 to 30 days. Default 7. |
| `limit` | integer | no | Items per source, 1 to 20. Default 10. |
| `hashtag` | boolean | no | true: the keyword is an exact hashtag; TikTok and Instagram return their top posts for it. |

Options some data sources take:

| Option | Works with | Meaning |
|---|---|---|
| `hashtag` | `TikTok`, `Instagram` | true = the keyword is an exact hashtag: return the platform's own top posts for it (official APIs) instead of a keyword search |
| `comments` | `YouTube`, `TikTok`, `Instagram`, `X`, `Reddit`, `Bluesky`, `Hacker News` | Top comments or replies for the first N items of each source (0 to 5, default 2) |

Data sources (`source`, 10): `News`, `YouTube`, `TikTok`, `Instagram`, `X`, `Reddit`, `Bluesky`, `Hacker News`, `Polymarket`, `GitHub`. Formats and categories: https://www.trendsmcp.ai/data-catalog.md

Request:

```bash
curl -X POST https://api.trendsmcp.ai/api \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"mode": "get_context", "keyword": "nvidia", "source": "News"}'
```

Response: Per source, the posts, videos, stories and markets about the keyword, best first.

| Field | Type | Meaning |
|---|---|---|
| `keyword` | string | The keyword you asked for. |
| `window_days` | number | How far back it looked. |
| `sources[].source` | string | The source. |
| `sources[].items[]` | array | Each item: kind, url, title, text, author, published, engagement (views, likes, comments, shares, score…), top_comments. |
| `sources[].error` | string \| null | Why a source returned nothing, when it failed. |

```json
{
  "keyword": "nintendo switch 2",
  "window_days": 7,
  "count": 1,
  "sources": [
    {
      "source": "YouTube",
      "count": 1,
      "error": null,
      "items": [
        {
          "kind": "video",
          "title": "Switch 2 review",
          "url": "https://youtube.com/watch?v=\u2026",
          "published": "2026-10-22T09:39:22Z",
          "engagement": {
            "views": 91542,
            "likes": 5997,
            "comments": 527
          }
        }
      ]
    }
  ]
}
```

### get_reviews

What customers say. What customers say about a brand, app, product or place: the matched listing with its all-time rating, then the newest reviews from each source with stars, the company's reply and helpful votes.

- Cost: 1 request per source (data type) in the call; 'all' = every review source
- MCP tool `get_reviews`; REST `"mode": "get_reviews"`

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `keyword` | string | yes | A brand, app, product or place name. |
| `source` | string | yes | One source, several separated by commas, or 'all'. |
| `days` | integer | no | Look back 1 to 365 days. Default 90. |
| `limit` | integer | no | Reviews per source, 1 to 20. Default 10. |

Options some data sources take:

| Option | Works with | Meaning |
|---|---|---|
| `country` | `App Store`, `Google Play`, `Amazon` | ISO 3166-1 alpha-2 country code (US, GB, JP). Boards, TikTok and review stores default to US; Google time series and growth default to worldwide |

Data sources (`source`, 3): `App Store`, `Google Play`, `Amazon`. Formats and categories: https://www.trendsmcp.ai/data-catalog.md

Request:

```bash
curl -X POST https://api.trendsmcp.ai/api \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"mode": "get_reviews", "keyword": "notion", "source": "App Store"}'
```

## Requests and plans

Every plan has a monthly pool of requests. Only successful calls count.

- `get_time_series`: 1 request per source (data type) in the call; 'all' = every keyword source
- `get_growth`: 1 request per source (data type) in the call, every window included; 'all' = every keyword source
- `get_top_trends`: 1 request per 10 rows per board: limit 100 (the default) = 10 requests per board
- `get_context`: 1 request per source (data type) in the call; 'all' = every context source
- `get_reviews`: 1 request per source (data type) in the call; 'all' = every review source
- `get_usage`: Free. MCP only: your plan, requests used and left, reset date.

| Plan | Monthly | Billed yearly | Requests a month | Keyword alerts | Top trends rows |
|---|---|---|---|---|---|
| Free | $0 | - | 100 | - | Full board |
| Starter | $19/mo | $16/mo ($192 a year) | 1,000 | 10 | Full board |
| Pro | $49/mo | $39/mo ($468 a year) | 5,000 | 50 | Full board |
| Business | $199/mo | $159/mo ($1,910 a year) | 25,000 | 250 | Full board |

Prices and billing: https://www.trendsmcp.ai/pricing

## Errors

REST answers HTTP 200 with an envelope: `{"statusCode": 400, "body": "…"}`. Read `statusCode`, then parse `body`. A missing or wrong key is the exception: HTTP 401 (`missing_api_key`) or 403 (`invalid_api_key`), with the error object as the body. Errors carry an `error` code and a `message`. Over MCP, a failed call sets `isError` on the tool result. Failed calls are free.

| Code | Meaning |
|---|---|
| `missing_parameter` | A required field is missing, e.g. type on get_top_trends. |
| `invalid_source` | The source or type is not one we serve; the message lists the allowed values. |
| `invalid_mode` | The mode is not one of the tools. |
| `invalid_request` | The body is malformed or a parameter value is not allowed. |
| `no_data` | Nothing matched this keyword on this source. |
| `source_unavailable` | The upstream source did not answer; try again later. |
| `growth_calculation_failed` | Growth could not be computed for that window (e.g. not enough history). |
| `internal_error` | Unexpected error. The body has a request_id; send it to support. |
| `missing_api_key` | No key was sent. Send it in the Authorization header as Bearer <key>. REST answers HTTP 401. |
| `invalid_api_key` | The key is mistyped or was regenerated. Get or copy your key on /account. REST answers HTTP 403. |
| `monthly_limit_reached` | The plan's monthly requests are used and there are no credits left. The message has links to buy credits (they never expire) or pick a plan. Over MCP the tool result has isError with the same text. get_usage shows what is left. |

```json
{"statusCode": 400, "body": "{\"error\": \"missing_parameter\", \"message\": \"The 'type' parameter is required\"}"}
```
