# reddapi.dev Reddit Search API API

> reddapi.dev Reddit Search API is a Reddit intent-lead engine: semantic vector search plus AI intent scoring over Reddit posts and comments, exposed as a REST API and an MCP server. Ask in natural language instead of guessing keywords, and get results classified by lead type, sentiment, and industry.

## API Base URL

https://reddapi.dev/api/v1

## Authentication

All API requests require authentication via Bearer token:

```
Authorization: Bearer $REDDAPI_KEY
```

API keys are available in your account dashboard after subscribing to a paid plan.

## Endpoints

### POST /api/v1/leads

Lead Search - The flagship endpoint. Finds Reddit posts and comments showing buying
intent for what you sell, and scores each one.

**Request Body:**
- `query` (string, required): Natural language description of the leads you want
- `limit` (number, optional): Maximum results (default: 20, max: 50)

**Response Fields:**
- `results[].id`: Post or comment ID
- `results[].kind`: `post` or `comment`
- `results[].subreddit`: Subreddit name
- `results[].author`: Reddit username
- `results[].content`: Matched text
- `results[].upvotes`: Number of upvotes
- `results[].created`: ISO timestamp
- `results[].relevance`: Semantic relevance score (0-1)
- `results[].lead_score`: Buying-intent score (0-100)
- `results[].lead_type`: One of `pain_point`, `solution_request`, `complaint`, `feature_request`, `comparison`
- `results[].pain_point`: Extracted pain point
- `results[].opportunity`: Extracted opportunity

### POST /api/v1/search/semantic

Semantic Search (AI Search) - Search Reddit conversations using natural language queries with AI-powered semantic understanding.

**Request Body:**
- `query` (string, required): Natural language search query
- `limit` (number, optional): Maximum results to return (default: 20)

**Response Fields:**
- `results[].id`: Post ID
- `results[].title`: Post title
- `results[].content`: Post content
- `results[].subreddit`: Subreddit name
- `results[].upvotes`: Number of upvotes
- `results[].comments`: Number of comments
- `results[].created`: ISO timestamp
- `results[].relevance`: Relevance score (0-1)
- `results[].sentiment`: Sentiment analysis (positive/negative/neutral)
- `results[].url`: Reddit URL
- `ai_summary`: AI-generated summary of results

### POST /api/v1/search/vector

Vector Search - High-speed vector similarity search on Reddit posts.

**Request Body:**
- `query` (string, required): Search query
- `limit` (number, optional): Maximum results (default: 30)
- `start_date` (string, optional): Filter start date (YYYY-MM-DD)
- `end_date` (string, optional): Filter end date (YYYY-MM-DD)

**Response Fields:**
- `results[].id`: Post ID
- `results[].title`: Post title
- `results[].content`: Post content
- `results[].subreddit`: Subreddit name
- `results[].upvotes`: Number of upvotes
- `results[].comments`: Number of comments
- `results[].created`: ISO timestamp
- `results[].similarity_score`: Similarity score (0-1)
- `results[].url`: Reddit URL

### POST /api/v1/trends

Trending Topics - Discover trending topics and discussions on Reddit.

**Request Body:**
- `start_date` (string, required): Start date (YYYY-MM-DD)
- `end_date` (string, required): End date (YYYY-MM-DD)
- `limit` (number, optional): Maximum trends to return (default: 20)

**Response Fields:**
- `trends[].id`: Trend ID
- `trends[].topic`: Topic name
- `trends[].post_count`: Number of posts
- `trends[].total_upvotes`: Total upvotes
- `trends[].total_comments`: Total comments
- `trends[].avg_sentiment`: Average sentiment score
- `trends[].top_subreddits`: Array of top subreddits
- `trends[].trending_keywords`: Array of keywords
- `trends[].trend_score`: Trend score
- `trends[].growth_rate`: Growth rate percentage

## Plans and Rate Limits

The monthly quota is shared between UI (Explorer / Leads) usage and API calls.

| Plan | Price | Monthly Quota | Rate Limit |
|------|-------|---------------|------------|
| Free | Free | API not available | N/A |
| Lite | $19.9/month | 500 requests/month | 50 requests/minute |
| Starter | $49/month | 5,000 requests/month | 50 requests/minute |
| Pro | $99/month | 15,000 requests/month | 100 requests/minute |
| Team | $249/month | 50,000 requests/month | 200 requests/minute |

Yearly billing is available on every paid plan at roughly ten months' price.
Paid plans include a 14-day cancellation right. See https://reddapi.dev/pricing for the
authoritative, current numbers.

## Response Headers

All paid API responses include:
- `X-RateLimit-Limit`: Your rate limit
- `X-RateLimit-Remaining`: Remaining requests
- `X-RateLimit-Reset`: Reset timestamp

## Error Codes

- `401`: Unauthorized - Invalid or missing API key
- `403`: Forbidden - Subscription required or quota exceeded
- `429`: Too Many Requests - Rate limit exceeded
- `500`: Internal Server Error

## MCP Server

An MCP server is available so AI agents can query Reddit directly. Setup instructions:
https://reddapi.dev/mcp

## Links

- Documentation: https://reddapi.dev/developers
- MCP Server: https://reddapi.dev/mcp
- Lead Search UI: https://reddapi.dev/leads
- Semantic Search UI: https://reddapi.dev/explore
- Pricing: https://reddapi.dev/pricing
- Account Dashboard: https://reddapi.dev/account