/reddit-insights

name: reddit-insights
description: Search Reddit posts by meaning via the reddapi.dev index.
version: 1.0.0
author: lignertys, Hermes Agent
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [Reddit, Search, Market Research, User Research, Trends, Validation]
    category: research
    related_skills: [duckduckgo-search, searxng-search]
    homepage: https://reddapi.dev
    config:
      reddapi_api_key: API key from https://reddapi.dev/account

Reddit Insights Skill

Reddit is where people complain, compare, and ask for alternatives before they ever fill out a survey. This skill queries that through [reddapi.dev](https://reddapi.dev): semantic search by meaning across the archive, plus site-wide trend momentum and subreddit lookup, with no Reddit OAuth or registered app.

It reads a third-party index rather than Reddit itself, so it is a research tool, not a substitute for the official API where data provenance matters. It cannot post, cannot read private or quarantined subreddits, and cannot walk live comment trees.

When to Use

• Mining how people describe a problem in their own words, before naming a

product or writing copy

• Comparing two tools by what users report after switching between them
• Checking whether a topic is gaining or losing momentum before committing
• Finding which subreddits actually discuss a niche, ahead of reading them

**Do not use when:** you already have a thread URL (fetch it with `web_extract`), you need the comment tree, or the query is not in English. The index is English-dominant.

Related: `reddit-leads` for B2B lead scoring on the same provider, `reddit-search-api` for a bare endpoint reference.

Prerequisites

• Python 3.9+ (the shipped script is stdlib only, no install step)
• `REDDAPI_API_KEY` exported in the shell that runs the request

Handling the key:

• Reference it only as `$REDDAPI_API_KEY`. Never substitute the literal value

into a command, a file, a code block, or a reply.

• Never ask the user to paste the key in chat. If they send it anyway, do not

repeat it back, do not write it to a file, and suggest rotating it at https://reddapi.dev/account.

• Never echo, print, or log the key, and never commit it.
• If it is unset, stop and tell the user to export it themselves. Do not run

that command with a value on their behalf.

• On a failed request, report the HTTP status and the response body only,

never the request headers.

Quotas are plan-based, not unlimited, and the monthly allowance is a shared pool: web-app searches, API calls, and lead searches draw on one counter. An invalid or exhausted key returns `429`, not `401`.

**Optional MCP server.** reddapi.dev also serves MCP over streamable HTTP at `https://reddapi.dev/api/mcp` with an `Authorization: Bearer` header. Set it up explicitly before referring to its tools (`reddit_semantic_search`, `reddit_vector_search`, `reddit_list_subreddits`, `reddit_get_subreddit`, `reddit_get_trends`).

How to Run

Call the shipped helper `scripts/reddapi.py` with the `terminal` tool:

python3 scripts/reddapi.py semantic "frustrated with project management tools" --limit 100
python3 scripts/reddapi.py semantic "best productivity tools for remote teams" --summary
python3 scripts/reddapi.py vector "AI coding agents" --start 2026-01-01 --end 2026-07-30
python3 scripts/reddapi.py trends --start 2026-07-01 --end 2026-07-30 --limit 10
python3 scripts/reddapi.py subreddits --search programming --limit 100
python3 scripts/reddapi.py subreddit programming

Search commands print one line per post (score, subreddit, upvotes, comments, date, title, URL). Add `--raw` for the full JSON. Exit codes: `0` ok, `1` API or network error, `2` missing key.

Full endpoint parameters, response schemas, and status codes live in `references/api-reference.md`.

Quick Reference

Which search mode, because the two are not interchangeable:

| | Semantic (default) | Vector | |---|---|---| | Coverage | full archive | full archive | | `limit` | default 20, max 100, filled exactly | default 30, max 100, filled exactly | | Date filter | none | `start_date` / `end_date`, applied | | Speed | 2.9s cold, ~12h cache per query | 835ms server time at `limit: 100` | | Extras | LLM keyword extraction, opt-in `ai_summary` | none | | Score field | `relevance` | `similarity_score` |

**Default to semantic. Drop to vector only when you need a date range.** Both cover the same archive and fill `limit` exactly, so the date filter is the only thing vector gives you that semantic does not.

Query patterns worth reusing:

| Pattern | Good for | |---|---| | `[competitor] problems complaints` | competitor and market research | | `I wish there was an app that` | niche and gap discovery | | `frustrated with [category]` | pain point mining | | `switching from [product] to` | displacement signal, positioning | | `trends` endpoint over a 30-day window | momentum before committing |

Procedure

1. **Scope with one broad semantic query.** If the archive has no coverage for the topic, that shows up in the first call, at full `limit`. 2. **Phrase the query as a person would.** Full sentences with emotion words pull stronger opinions than noun phrases. 3. **Widen with more queries, not a bigger limit.** `limit` caps at 100 and is clamped silently above that. Three angles at 100 beat one at 300. 4. **Switch to vector search when a date window matters.** It is the only mode that accepts one, and the only reason to leave semantic search. Use the window to compare two periods rather than to trim one result set. 5. **Check momentum separately.** `trends` is global, not filterable by topic, so use it to spot what Reddit is talking about, not to score a specific idea. Topics are named entities; `growth_rate` compares the window with the equal-length one before it (`null` = new). It is not a leading indicator of Google search interest. 6. **Follow high-engagement hits back t