# Socialytics API reference

> Socialytics gives AI assistants and code live trend data: 53 data sets from 27 platforms (Google, Google Images, Google News, Google Shopping, YouTube, Wikipedia, TikTok, Amazon, Pinterest, npm, PyPI, Steam, Google Play, App Store, GitHub, Google Trends, IMDb, Open Library, Polymarket, Reddit, Web, Spotify, Substack, X, Instagram, Bluesky, Hacker News), through 5 tools over MCP or a REST API. About five years of weekly history where the source has it. One free API key for both.

Markdown of https://socialytics.dev/docs. Generated from the API catalog on 2026-11-03.

## Endpoints

- MCP, sign in (Claude, ChatGPT): `https://socialytics.dev/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://socialytics.dev/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 call.
- `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 call, every window included.
- `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: MCP: 1 request per 10 rows, at most 10 per call. REST: 1 request per call.
- `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: MCP: 1 request per source, at most 5 per call. REST: one source per call, 1 request.
- `get_top_posts`: Top posts for one hashtag. Live top posts for one hashtag, fetched on every call. Business plan. Cost: 1 request per call.
- `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 call
- 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 | Exactly one keyword source. |

Options some data sets 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 and TikTok 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 sets (`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://socialytics.dev/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 call, every window included
- 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, or several separated by commas. |
| `percent_growth` | string[] | no | Window presets such as 3M, 12M or YTD. Default 12M. |

Options some data sets 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 and TikTok 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 sets (`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://socialytics.dev/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: MCP: 1 request per 10 rows, at most 10 per call. REST: 1 request per call
- MCP tool `get_top_trends`; REST `"mode": "get_top_trends"`

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `type` | string | yes | Exactly one live board. |
| `limit` | integer | no | 1 to 200. Default 25. |
| `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 sets 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 and TikTok 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 sets (`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://socialytics.dev/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. |
| `note` | string | Your plan's limit on this board, when it applies (e.g. top 10, delayed 24 hours). |

```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: MCP: 1 request per source, at most 5 per call. REST: one source per call, 1 request
- MCP tool `get_context`; REST `"mode": "get_context"`

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `keyword` | string | yes | Any name or phrase. |
| `source` | string | yes | One source, or up to 5 separated by commas. |
| `days` | integer | no | Look back 1 to 30 days. Default 7. |
| `limit` | integer | no | Items per source, 1 to 20. Default 10. |

Options some data sets take:

| Option | Works with | Meaning |
|---|---|---|
| `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 sets (`source`, 10): `News`, `YouTube`, `TikTok`, `Instagram`, `X`, `Reddit`, `Bluesky`, `Hacker News`, `Polymarket`, `GitHub`. Formats and categories: https://socialytics.dev/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_top_posts

Top posts for one hashtag. Live top posts for one hashtag, fetched on every call. Business plan.

- Cost: 1 request per call. Business plan and up.
- MCP tool `get_top_posts`; REST `"mode": "get_top_posts"`

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `keyword` | string | yes | The hashtag, with or without #. |
| `source` | string | yes | TikTok or Instagram. |
| `limit` | integer | no | 1 to 20. Default 20. |

Data sets (`source`, 2): `TikTok`, `Instagram`. Formats and categories: https://socialytics.dev/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_posts", "keyword": "booktok", "source": "TikTok"}'
```

Response: The top posts for the hashtag right now, fetched live on every call.

| Field | Type | Meaning |
|---|---|---|
| `keyword` | string | The hashtag, without #. |
| `source` | string | tiktok or instagram. |
| `posts[].rank` | number | Position on the hashtag page. |
| `posts[].caption` | string | The post's text. |
| `posts[].author` | string \| null | The account, where available. |
| `posts[].plays / likes / comments` | number \| null | Engagement, where the source has it. |
| `posts[].posted` | string | When it was posted. |
| `posts[].url` | string | Link to the post. |

```json
{
  "keyword": "booktok",
  "source": "tiktok",
  "count": 1,
  "posts": [
    {
      "rank": 1,
      "caption": "5 books that wrecked me",
      "author": "readwithme",
      "plays": 1840221,
      "likes": 220114,
      "posted": "2026-10-25",
      "url": "https://www.tiktok.com/@readwithme/video/\u2026"
    }
  ]
}
```

## Requests and plans

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

- `get_time_series`: 1 request per call
- `get_growth`: 1 request per call, every window included
- `get_top_trends`: MCP: 1 request per 10 rows, at most 10 per call. REST: 1 request per call
- `get_context`: MCP: 1 request per source, at most 5 per call. REST: one source per call, 1 request
- `get_top_posts`: 1 request per call (Business plan)
- `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 | Top Posts |
|---|---|---|---|---|---|---|
| Free | $0 | - | 100 | - | Top 10, 24h delay | - |
| Starter | $19/mo | $16/mo ($192 a year) | 1,000 | 10 | Top 25 | - |
| Pro | $49/mo | $39/mo ($468 a year) | 5,000 | 50 | Top 100 | - |
| Business | $199/mo | $159/mo ($1,910 a year) | 25,000 | 250 | Full board | yes |

Prices and billing: https://socialytics.dev/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. |
| `plan_required` | The tool needs a higher plan (Top Posts: Business). |
| `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\"}"}
```