# Reddit Insights API

> Reddit Insights is an AI-powered Reddit search engine that crawls millions of Reddit posts daily and provides semantic search capabilities.

## API Base URL

https://reddit-insights.com/api/v1

## Authentication

All API requests require authentication via Bearer token:

```
Authorization: Bearer YOUR_API_KEY
```

API keys are available in your account dashboard after subscribing to a Pro or Enterprise plan.

## Endpoints

### 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

### GET /api/v1/sonars (FREE)

List Sonars - Get all your monitoring sonars. Does not count toward API quota.

**Response Fields:**
- `sonars[].id`: Sonar ID
- `sonars[].name`: Sonar name
- `sonars[].query`: Search query
- `sonars[].description`: Description
- `sonars[].enabled`: Is enabled
- `sonars[].schedule`: Execution schedule (daily/weekly)
- `sonars[].lastExecutedAt`: Last execution timestamp
- `sonars[].nextExecutionAt`: Next execution timestamp

### POST /api/v1/sonars (FREE)

Create Sonar - Create a new monitoring sonar. Does not count toward API quota.

**Request Body:**
- `name` (string, required): Sonar name
- `query` (string, required): Search query to monitor
- `description` (string, optional): Description
- `schedule` (string, optional): "daily" or "weekly"
- `triggers.keywords` (array, optional): Alert keywords
- `triggers.sentiment` (string, optional): Sentiment filter
- `triggers.minNewPosts` (number, optional): Minimum posts threshold
- `notifyEmail` (boolean, optional): Enable email notifications
- `notifySlack` (boolean, optional): Enable Slack notifications

### GET /api/v1/sonars/{id}/executions (FREE)

Get Sonar Executions - Get execution history for a specific sonar. Does not count toward API quota.

**Query Parameters:**
- `limit` (number, optional): Maximum results (default: 50)
- `offset` (number, optional): Pagination offset (default: 0)

**Response Fields:**
- `executions[].id`: Execution ID
- `executions[].status`: Status (completed/failed)
- `executions[].executedAt`: Execution timestamp
- `executions[].newPostsCount`: Number of new posts found
- `executions[].triggered`: Was alert triggered
- `executions[].triggerReason`: Reason for trigger
- `executions[].notificationSent`: Was notification sent
- `executions[].aiSummary`: AI summary of results

### GET /api/v1/sonars/executions/{executionId} (FREE)

Get Execution Detail - Get detailed search results from a specific sonar execution. Does not count toward API quota.

**Response Fields:**
- `execution.id`: Execution ID
- `execution.sonarId`: Sonar ID
- `execution.sonarName`: Sonar name
- `execution.status`: Status
- `execution.executedAt`: Execution timestamp
- `execution.query`: Search query used
- `execution.keywords`: Extracted keywords
- `execution.newPostsCount`: New posts count
- `execution.aiSummary`: AI summary
- `results[]`: Array of search results (same as semantic search)
- `stats.totalPosts`: Total posts
- `stats.avgUpvotes`: Average upvotes
- `stats.avgComments`: Average comments
- `stats.topSubreddits`: Top subreddits with counts
- `stats.sentimentBreakdown`: Sentiment distribution

## Rate Limits

| Plan | Monthly Quota | Rate Limit |
|------|---------------|------------|
| Free | 100 requests/hour | N/A - API not available |
| Pro | 10,000 requests/month | 60 requests/minute |
| Enterprise | Unlimited | Custom limits |

## 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

## Links

- Documentation: https://reddit-insights.com/developers
- Pricing: https://reddit-insights.com/pricing
- Account Dashboard: https://reddit-insights.com/account