MCP & API Reference

Query behavioral trend data across search, social, and commerce platforms. Use MCP to query via an AI assistant like Claude or ChatGPT, or the REST API to integrate directly into your code.

Authentication

An account is required to connect — both for MCP and the REST API. Sign up for free with your email and we'll send your API key instantly (100 requests/month, no credit card). Every request must then include that API key in the Authorization header. The Bearer prefix is optional; the bare key works too. How calls are counted is defined below (same rules for REST and MCP).

curl -X POST https://api.trendsmcp.ai/api \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"get_time_series","source":"google search","keyword":"bitcoin"}'

import requests

res = requests.post(
    "https://api.trendsmcp.ai/api",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"mode": "get_time_series", "source": "google search", "keyword": "bitcoin"}
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.trendsmcp.ai/api", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ mode: "get_time_series", source: "google search", keyword: "bitcoin" })
});
const data = await res.json();

What counts as a request

Each successful hit against the data API uses one unit of your monthly quota. Failed requests are free: only successful (2xx) calls count.

Data Sources

Two types of sources are available, accessed via different operations. Keyword sources return a historical time series or growth metric for a specific keyword. Live feeds return the top-ranked items on a platform right now. No keyword needed.

Keyword sources (get_time_series & get_growth)

Pass the source value below in your request body alongside keyword. On REST, set mode to "get_time_series" (time series) or "get_growth" (period-over-period %). For get_growth, pass one source or a comma-separated list. For get_time_series, pass one source per request. Matching is case-insensitive.

Live boards (get_top_trends)

Pass the type value below with mode: "get_top_trends". No keyword needed. Returns the current ranked leaders on that platform, or the biggest climbers with sort: "rank_change".

Top posts (get_top_posts)

Pass a hashtag as keyword and one source below.

Every parameter, category list and a call to copy for each data set: Data catalog.

API modes

Every call is POST https://api.trendsmcp.ai/api with Authorization: Bearer <key> (the Bearer prefix is optional; the bare key works too). Pick the operation with the mode field in the JSON body.

Canonical mode names match the MCP tools. Aliases: get_trends, trends, time_series, and lookup all mean get_time_series; growth means get_growth; top_trends means get_top_trends. Prefer the canonical names in user-facing REST examples.

Copy-paste examples

// Time series
{ "mode": "get_time_series", "source": "google search", "keyword": "bitcoin" }

// Growth
{ "mode": "get_growth", "source": "google search", "keyword": "bitcoin", "percent_growth": ["12M"] }

// Top trends
{ "mode": "get_top_trends", "type": "Google Trends", "limit": 10 }

// Top trends, biggest climbers this week (sort: "rank" is the default)
{ "mode": "get_top_trends", "type": "Amazon Best Sellers by Category", "category": "Toys Games", "sort": "rank_change", "window": "7d", "limit": 10 }

Quota: 1 request per source + keyword. Every plan gets the full history. Full rules

Request body

Response fields

{
  "mode":    "get_time_series",
  "source":  "google search",
  "keyword": "bitcoin"
}

[
  {
    "date":    "2026-03-21",
    "value":   47,
    "volume":  25853617,
    "keyword": "bitcoin",
    "source":  "google search"
  },
  // ... up to 261 weekly data points
]

Quota: 1 request per source + keyword (all percent_growth periods in that call). Every plan gets the full history. Full rules

Request body

Growth windows

Any whole number plus a D, W, M, or Y suffix works, up to 5 years (e.g. 7D, 17D, 45D, 3M, 18M, 2Y), plus MTD, QTD, and YTD. Common examples:

Custom date range object (REST only)

Custom date objects are REST-only; MCP accepts the string windows above.

Response fields

{
  "mode":           "get_growth",
  "source":         "google search",
  "keyword":        "bitcoin",
  "percent_growth": ["12M"]
}

{
  "mode":    "get_growth",
  "source":  "amazon",
  "keyword": "nike",
  "percent_growth": [
    {
      "name":     "Last Year",
      "recent":   "2025-12-31",
      "baseline": "2024-12-31"
    }
  ]
}

{
  "search_term": "nike",
  "data_source": "google search",
  "results": [
    {
      "period":           "12M",
      "growth":           -12.31,
      "direction":        "decrease",
      "recent_date":      "2026-03-21",
      "baseline_date":    "2025-03-22",
      "recent_value":     57,
      "baseline_value":   65,
      "volume_available": true,
      "recent_volume":    24158298,
      "baseline_volume":  27548936,
      "volume_growth":    -12.31
    }
  ],
  "metadata": {
    "total_data_points":      261,
    "calculations_completed": 1,
    "all_successful":         true
  }
}

Quota: MCP is 1 credit per 10 requested rows (max 10 per call). REST is 1 per POST. Full rules

Request body

Available boards

{
  "mode":  "get_top_trends",
  "type":  "Google Trends",
  "limit": 10
}

{
  "mode":     "get_top_trends",
  "type":     "Google Trends by Category",
  "category": "Games",
  "limit":    10
}

{
  "mode":     "get_top_trends",
  "type":     "Amazon Best Sellers by Category",
  "category": "Toys Games",
  "sort":     "rank_change",
  "window":   "7d",
  "limit":    10
}

{
  "as_of_ts": "2026-03-26T22:22:25Z",
  "type":     "Google Trends",
  "limit":    10,
  "count":    10,
  "data": [
    [1, "chuck norris"],
    [2, "project hail mary"],
    [3, "bachelorette cancelled"]
    // ... [rank, name] pairs
  ]
}

MCP / AI

AI Prompts

When using Trends Agents through an AI assistant (Claude, ChatGPT, Cursor, etc.), include "using Trends Agents" or "via Trends Agents" in your prompt so the AI routes to the MCP instead of a web search.

Errors

The REST transport always returns HTTP 200. The real outcome is in the payload envelope: {"statusCode": <int>, "body": "<json string>"}. Check statusCode, then parse body. Error bodies carry an error string (one of the codes below) and a message. On MCP, tool failures set isError=true on the tool result.

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