Reddit Trends API
Reddit discussion volume and subreddit growth over time. Free key at trendsapi.ai
Open source Repository Open in the app JSON README (API)
About
Reddit discussion volume and subreddit growth over time. Free key at trendsapi.ai
Details
- Kind
- MCP servers
- Topic
- Social & content
- Publisher
- ai.trendsapi
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 1.0.1
- Last push
- 2026-08-18T15:23:26Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 03:00:42
- Updated
- 2026-08-29 03:00:42
- Origin id
ai.trendsapi/reddit
README
# Reddit discussion-attention API
Reddit attention trends via the Trends API. Subreddit history, growth, and live hot posts. Not PRAW.
[](LICENSE)
[](https://pypi.org/project/trendsapi-reddit/)
[](https://trendsapi.ai)
Key: [trendsapi.ai/#get-key](https://trendsapi.ai/#get-key). HTTP contract and every source: [trendsapi-ai/trendsapi](https://github.com/trendsapi-ai/trendsapi).
## Authentication
```bash
pip install trendsapi-reddit
export TRENDSAPI_KEY=your_key
```
Python 3.9+. Same key as the HTTP API.
```python
from trendsapi_reddit import TrendsAPI
client = TrendsAPI() # TRENDSAPI_KEY
# client = TrendsAPI(api_key="YOUR_KEY")
```
Keyword helpers default to `source: "reddit"`. Pass `source=` to hit any other platform with the same client. Official full client (every source, no preset): [`trendsapi`](https://pypi.org/project/trendsapi/).
## Methods
| Method | REST `mode` | Returns |
|---|---|---|
| `get_time_series(keyword, source=, data_mode=)` | `get_time_series` | `list[TrendsDataPoint]` |
| `get_growth(keyword, percent_growth=, source=, data_mode=)` | `get_growth` | `GetGrowthResponse` |
| `get_live(limit=, offset=, category=)` | `get_top_trends` | `GetTopTrendsResponse` |
| `get_top_trends(type=, ...)` | `get_top_trends` | `GetTopTrendsResponse` |
`source` is lowercase (`reddit`). `type` is exact (`Reddit Hot Posts`). Mixing them is a 400.
```python
from trendsapi_reddit import TrendsAPI
client = TrendsAPI() # TRENDSAPI_KEY
# client = TrendsAPI(api_key="YOUR_KEY")
series = client.get_time_series("wallstreetbets")
print(series[-1].date, series[-1].value)
growth = client.get_growth("wallstreetbets", percent_growth=["3M", "12M"])
print(growth.results[0].growth, growth.results[0].direction)
hot = client.get_live(limit=10)
print(hot.data) # [[1, "..."], ...]
```
## get_time_series
```python
points = client.get_time_series("wallstreetbets")
```
Each point:
| Field | Always | Meaning |
|---|---|---|
| `date` | yes | `YYYY-MM-DD` |
| `value` | yes | 0-100 index for this series |
| `keyword` | yes | Echo |
| `volume` | no | Absolute volume when available |
| `source` or `datatype` | no | Pipeline label |
Python returns `list[TrendsDataPoint]`. Use `.date` and `.value`, not `["date"]`.
JS returns the same fields as object properties.
## get_growth
```python
g = client.get_growth("wallstreetbets", percent_growth=["12M", "3M", "YTD"])
print(g.results[0].growth, g.results[0].direction)
```
`percent_growth` default: `["12M"]`. Presets: `7D` `14D` `30D` `1M` `2M` `3M` `6M` `9M` `12M`/`1Y` `18M` `24M`/`2Y` `36M`/`3Y` `48M` `60M`/`5Y` `MTD` `QTD` `YTD`. Custom: `{"name": "Launch", "recent": "2024-06-01", "baseline": "2024-01-01"}`.
| Field | Meaning |
|---|---|
| `search_term` | Keyword |
| `data_source` | Source |
| `results` | One object per window (`period`, `growth`, `direction`, dates, values) |
| `metadata` | Counts / success flag |
Several windows still count as one request. Python: `growth.results[0].growth`. JS: `growth.results[0].growth`.
## get_live
```python
hot = client.get_live(limit=10)
```
| Field | Meaning |
|---|---|
| `as_of_ts` | Snapshot time |
| `type` | Feed name |
| `limit`, `offset`, `count` | Pagination |
| `data` | `[rank, label]` rows |
Python: `hot.data`. JS: `hot.data`. Optional `offset=` and `category=` (`Amazon Best Sellers by Category`, `Top Websites` only).
## Async
```python
import asyncio
from trendsapi_reddit import AsyncTrendsAPI
async def main():
c = AsyncTrendsAPI()
return await asyncio.gather(
c.get_time_series("wallstreetbets"),
c.get_time_series("wallstreetbets", source="google search"),
)
asyncio.run(main())
```
Each 200 is one billed request.
## Pandas
```python
from dataclasses import asdict
import pandas as pd
from trendsapi_reddit import TrendsAPI
df = pd.DataFrame(asdict(p) for p in TrendsAPI().get_time_series("wallstreetbets"))
df["date"] = pd.to_datetime(df["date"])
print(df.set_index("date")["value"].resample("ME").mean().tail())
```
## Call (curl)
| Field | Value |
|---|---|
| Endpoint | `POST https://api.trendsapi.ai/api` |
| Auth | `Authorization: Bearer $TRENDSAPI_KEY` |
| History | `source: reddit` with `get_time_series` or `get_growth` |
| Keyword | Subreddit or topic, no r/ prefix, e.g. wallstreetbets |
| Live `type` | Reddit Hot Posts, Reddit World News |
```bash
curl -sS -X POST https://api.trendsapi.ai/api \
-H "Authorization: Bearer $TRENDSAPI_KEY" \
-H "Content-Type: application/json" \
-d '{"mode":"get_time_series","source":"reddit","keyword":"wallstreetbets"}'
```
## Source notes
- `source` is always `reddit`. The community goes in `keyword`.
- `value` is not subscriber count.
- You cannot post, vote, or stream comments.
## Errors
| HTTP | Client |
|---|---|
| 200 | Parsed payload. Python dataclasses / JS typed objects |
| 400 | Raises. Fix `source` or `type` spelling |
| 401 | Raises. Check `TRENDSAPI_KEY` |
| 404 | Raises. No series for that keyword. Do not retry |
| 429 | Raises. Quota |
| 5xx | Client retries, then raises |
The HTTP `body` field is a JSON string. SDKs decode it. Raw curl must parse `body` a second time.
Site: [https://trendsapi.ai/trends/reddit-trends](https://trendsapi.ai/trends/reddit-trends).
## License
MIT. See [LICENSE](LICENSE).