--- name: reddit-search description: Search and analyze Reddit conversations using reddapi.dev semantic AI search API. Use when researching user opinions, market trends, product feedback, competitor analysis, or any topic discussed on Reddit. allowed-tools: WebFetch, Bash(curl *) --- # reddapi.dev Reddit Search API - Reddit Semantic Search Search Reddit using natural language questions, not keywords. Get AI-powered sentiment analysis and summaries. ## Authentication All API requests require a Bearer token in the Authorization header: ``` Authorization: Bearer $REDDAPI_KEY ``` Get your API key at https://reddapi.dev/account --- ## Use Cases with Examples ### 1. Product Research Find what users really think about products: ```bash curl -X POST "https://reddapi.dev/api/v1/search" \ -H "Authorization: Bearer $REDDAPI_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "What do people hate about the iPhone 15 camera?", "limit": 20}' ``` ### 2. Market Research Understand consumer pain points: ```bash curl -X POST "https://reddapi.dev/api/v1/search" \ -H "Authorization: Bearer $REDDAPI_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "Why are young people switching from traditional banks to neobanks?", "limit": 20}' ``` ### 3. Competitor Analysis See how users compare products: ```bash curl -X POST "https://reddapi.dev/api/v1/search" \ -H "Authorization: Bearer $REDDAPI_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "Notion vs Obsidian which one do developers prefer and why?", "limit": 20}' ``` ### 4. Feature Validation Validate product ideas before building: ```bash curl -X POST "https://reddapi.dev/api/v1/search" \ -H "Authorization: Bearer $REDDAPI_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "What features do users wish Spotify had?", "limit": 20}' ``` ### 5. Time-Filtered Search Restrict a search to a date range. Use `/api/v1/search` with `start_time`/`end_time` - it is the same default endpoint, so you keep query rewriting, re-ranking and promotional filtering while the window is pushed down into the vector index. ```bash curl -X POST "https://reddapi.dev/api/v1/search" \ -H "Authorization: Bearer $REDDAPI_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "What problems do owners report with Tesla autopilot?", "limit": 30, "start_time": "2026-01-01", "end_time": "2026-06-30"}' ``` ### 6. Discover Trending Topics Find what's trending in a date range: ```bash curl -X POST "https://reddapi.dev/api/v1/trends" \ -H "Authorization: Bearer $REDDAPI_KEY" \ -H "Content-Type: application/json" \ -d '{"start_date": "2026-08-01", "end_date": "2026-08-31", "limit": 20}' ``` ### 7. Find Business Leads Discover pain points and opportunities: ```bash curl -X POST "https://reddapi.dev/api/v1/leads" \ -H "Authorization: Bearer $REDDAPI_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "people frustrated with project management tools", "limit": 20}' ``` --- ## API Reference ### POST /api/v1/search AI-powered semantic search with sentiment analysis and AI summary. **Default choice for search.** The query is rewritten into intent statements, candidates are re-ranked by a cross-encoder, and promotional/vendor posts are dropped before results are truncated. **Parameters:** | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | query | string | Yes | - | Natural language question | | limit | number | No | 20 | Max results (1-100) | | start_time | string | No | - | Restrict to posts created on or after this time (YYYY-MM-DD or ISO 8601) | | end_time | string | No | - | Restrict to posts created on or before this time (YYYY-MM-DD or ISO 8601) | | include_summary | boolean | No | false | Generate the AI summary (adds a slow LLM call) | **Example:** ```bash curl -X POST "https://reddapi.dev/api/v1/search" \ -H "Authorization: Bearer $REDDAPI_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "What do developers think about TypeScript?", "limit": 20}' ``` **Response:** ```json { "success": true, "data": { "query": "What do developers think about TypeScript?", "results": [ { "id": "abc123", "title": "Finally switched our codebase to TypeScript", "content": "After 2 years of plain JS, we migrated to TS and...", "subreddit": "webdev", "upvotes": 892, "comments": 234, "created": "2024-03-15T10:30:00Z", "relevance": 0.95, "sentiment": "positive", "url": "https://reddit.com/r/webdev/comments/abc123" } ], "total": 20, "processing_time_ms": 1250, "ai_summary": "Developers generally favor TypeScript for larger projects due to type safety and better IDE support..." } } ``` --- ### POST /api/v1/search/vector Raw vector similarity search. The query is embedded and matched by cosine similarity, and that is all: **no query rewriting, no cross-encoder re-ranking, no promotional filtering** - all of which `/api/v1/search` does apply. On generic or open-ended phrasings this endpoint returns substantially noisier results (referral-code spam, unrelated "free/paid" chatter). **You probably want `/api/v1/search` instead.** A date range is *not* a reason to come here - `/api/v1/search` takes `start_time`/`end_time` and keeps the full relevance pipeline. Reach for this endpoint only for high-volume batch work where you have accepted the relevance loss in exchange for no LLM calls and lower latency. Date filtering covers the vector archive, which currently starts at 2026-01-01. A range ending before that returns zero results. **Parameters:** | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | query | string | Yes | - | Search query | | limit | number | No | 30 | Max results (1-100) | | start_date | string | No | - | Start date (YYYY-MM-DD or ISO 8601) | | end_date | string | No | - | End date (YYYY-MM-DD or ISO 8601) | **Example:** ```bash curl -X POST "https://reddapi.dev/api/v1/search/vector" \ -H "Authorization: Bearer $REDDAPI_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "electric vehicle charging problems", "limit": 30, "start_date": "2026-01-01", "end_date": "2026-06-30"}' ``` **Response:** ```json { "success": true, "data": { "query": "electric vehicle charging problems", "results": [ { "id": "vec001", "title": "EV charging station was broken again", "content": "Drove 20 miles to the nearest charging station...", "subreddit": "electricvehicles", "upvotes": 445, "comments": 123, "created": "2024-01-20T08:15:00Z", "similarity_score": 0.92, "url": "https://reddit.com/r/electricvehicles/comments/vec001" } ], "total": 30, "processing_time_ms": 320 } } ``` --- ### POST /api/v1/trends Named entities (products, people, games, shows, events) extracted daily from each day's top posts, aggregated over the window and compared against the equal-length window before it. Ranked by engagement; `growth_rate` is the change in mentions between the two windows. Today's data is computed the next morning, so query past days and read `coverage`. **Parameters:** | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | start_date | string | No | 7 days ago | Start date, UTC (YYYY-MM-DD or ISO 8601) | | end_date | string | No | yesterday | End date, UTC; window max 92 days. Omit both for the 7 days ending yesterday; give one for a single day | | limit | number | No | 20 | Max topics (1-100) | **Example:** ```bash curl -X POST "https://reddapi.dev/api/v1/trends" \ -H "Authorization: Bearer $REDDAPI_KEY" \ -H "Content-Type: application/json" \ -d '{"start_date": "2026-08-01", "end_date": "2026-08-31", "limit": 20}' ``` **Response:** ```json { "success": true, "data": { "trends": [ { "id": "trend_gta_6", "topic": "GTA 6", "kind": "game", "post_count": 41, "prior_post_count": 12, "growth_rate": 241.7, "total_upvotes": 45632, "total_comments": 8923, "days_active": 19, "first_seen": "2026-08-02", "top_subreddits": ["gaming", "GTA6", "pcgaming"], "trending_keywords": ["trailer", "delay", "leak", "release", "rockstar"], "sample_posts": [ { "id": "1n2abcd", "title": "GTA 6 trailer 3 breakdown", "subreddit": "gaming", "upvotes": 2341, "comments": 456, "created": "2026-08-15T10:30:00Z" } ], "trend_score": 30948.4 } ], "total": 20, "date_range": { "start": "2026-08-01", "end": "2026-08-31" }, "prior_date_range": { "start": "2026-07-01", "end": "2026-07-31" }, "coverage": { "days_requested": 31, "days_with_data": 30, "latest_day": "2026-08-30" }, "processing_time_ms": 850 } } ``` `growth_rate` is null for entities with no mentions in the prior window (brand new). `total_comments` is summed from crawl-time comment counts and is 0 for posts crawled before 2026-08-25. Ranking is by `trend_score`; sort client-side by `growth_rate` for what is rising. Reddit is a discussion feed, not a leading indicator: a 2026-08 comparison against Google Trends found it led Google in well under 1% of trending items. --- ### POST /api/v1/leads Find business leads and opportunities from Reddit discussions. **Parameters:** | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | query | string | Yes | - | Describe the leads you want to find | | limit | number | No | 20 | Max results to search for (1-50). Your plan caps how many are returned - see below | | days | number | No | - | Only include posts from the last N days. One of 1, 7, 30, 90. Omit for no time filter; other values fall back to 7 | **Plan cap:** the number of fully-scored leads returned is limited by your plan (Free returns 3; paid plans are unlimited). `total` is always the length of `results`; `total_candidates` is how many were found before the cap, and `is_limited` is true when the cap trimmed the list. **Example:** ```bash curl -X POST "https://reddapi.dev/api/v1/leads" \ -H "Authorization: Bearer $REDDAPI_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "people frustrated with CRM software", "limit": 20}' ``` **Response:** ```json { "success": true, "data": { "query": "people frustrated with CRM software", "results": [ { "id": "lead001", "title": "Our CRM is driving the sales team crazy", "content": "We've been using Salesforce for 2 years and...", "subreddit": "smallbusiness", "upvotes": 234, "comments": 87, "created": "2024-06-15T10:30:00Z", "relevance": 0.91, "lead_score": 85, "lead_type": "pain_point", "pain_point": "CRM too complex for small sales teams", "opportunity": "Simpler CRM alternative for SMBs", "industry": "SaaS", "target_product": "Salesforce", "url": "https://reddit.com/r/smallbusiness/comments/lead001" } ], "total": 20, "total_candidates": 20, "is_limited": false, "visible_limit": -1, "processing_time_ms": 2100 } } ``` --- ## Rate Limits | Plan | Price | Included Quota | Rate Limit | |------|-------|----------------|------------| | Free | $0 | 3 calls / 7 days | 3 req/min | | Lite | $19.9/mo | 500 requests/month | 50 req/min | | Starter | $49/mo | 5,000 requests/month | 50 req/min | | Pro | $99/mo | 15,000 requests/month | 100 req/min | | Team | $249/mo | 50,000 requests/month | 200 req/min | | Enterprise | Custom | Unlimited | 1000 req/min | The quota is one shared pool: UI searches, REST API calls and MCP tool calls all draw from the same counter. The Free plan's window is a rolling 7-day cycle, not a calendar month; paid plans reset with the monthly billing cycle. --- ## Error Codes | HTTP Code | Error | Description | |-----------|-------|-------------| | 400 | Bad Request | Invalid parameters (missing query, invalid date format) | | 401 | Unauthorized | Missing, malformed or unknown API key | | 403 | Forbidden | Key is valid, but your plan does not include API access | | 429 | Too Many Requests | Quota or rate limit exceeded - retry after the window resets | | 500 | Internal Error | Server error, retry with backoff | 401 / 403 / 429 are strictly distinct: 401 means the credential is bad, 403 means the credential is fine but the plan lacks the entitlement (waiting will not help), and 429 is the only one that means "out of quota". Do not treat 403 as a retryable rate limit. **Error Response:** ```json { "success": false, "error": "Query parameter is required and must be a non-empty string" } ``` --- ## Links - Get API Key: https://reddapi.dev/account - Pricing: https://reddapi.dev/pricing - Documentation: https://reddapi.dev/developers - MCP Server: https://reddapi.dev/mcp