Shell
Reddit Research Agent - API Reference
TypeScript API
Reddit Fetcher
fetchThread(url: string): Promise<ThreadData>
Fetch and parse a complete Reddit thread with all comments.
import { fetchThread } from './reddit';
const thread = await fetchThread('https://reddit.com/r/SaaS/comments/xyz/title/');
console.log(thread.post.title);
console.log(thread.metrics.totalComments);
console.log(thread.topComments[0].body);
searchSubreddit(subreddit, query?, options?): Promise<GoldmineScore[]>
Search a subreddit for matching threads.
import { searchSubreddit } from './reddit';
const threads = await searchSubreddit('SaaS', 'wish existed', {
sort: 'top',
time: 'year',
limit: 25
});
findGoldmineThreads(subreddit, queries?): Promise<GoldmineScore[]>
Run multiple goldmine searches and return deduplicated, scored results.
import { findGoldmineThreads } from './reddit';
// Uses default goldmine queries
const threads = await findGoldmineThreads('entrepreneur');
// Or specify custom queries
const customThreads = await findGoldmineThreads('smallbusiness', [
'software recommendation',
'tool for',
'automate'
]);
Analyzer
analyzeThread(data: ThreadData, options?): Promise<MarketInsight>
Analyze a thread using Claude and extract structured insights.
import { fetchThread } from './reddit';
import { analyzeThread } from './agent/analyzer';
const thread = await fetchThread(url);
const insights = await analyzeThread(thread, {
apiKey: process.env.ANTHROPIC_API_KEY
});
console.log(insights.painPoints);
console.log(insights.opportunities);
console.log(insights.summary);
quickAnalyze(data: ThreadData): Partial<MarketInsight>
Fast pattern-based analysis without Claude (free).
import { quickAnalyze } from './agent/analyzer';
const quick = quickAnalyze(thread);
console.log(quick.competitorMentions);
console.log(quick.buyingSignals);
Database
initDatabase(dbPath?: string): Database
Initialize SQLite database connection.
import { initDatabase } from './db';
const db = initDatabase('./my-research.db');
saveThreads(threads: GoldmineScore[]): number
Save scanned threads to database. Returns count saved.
import { saveThreads } from './db';
const count = saveThreads(goldmineThreads);
saveInsight(threadId, type, content, metadata?, confidence?): string
Save a market insight. Returns insight ID.
import { saveInsight } from './db';
const id = saveInsight(
'thread123',
'pain_point',
'Manual order processing is time-consuming',
{ frequency: 5, sentiment: 'frustrated' },
'high'
);
getInsightsByType(type, limit?): Insight[]
Query insights by type.
import { getInsightsByType } from './db';
const painPoints = getInsightsByType('pain_point', 50);
const opportunities = getInsightsByType('opportunity');
const competitors = getInsightsByType('competitor');
Agent Runner
runScanCycle(options?): Promise<ScanResult>
Run a single scan and analysis cycle.
import { runScanCycle } from './agent/runner';
const result = await runScanCycle({
dbPath: './research.db',
maxThreadsPerScan: 20,
minGoldmineScore: 15,
useClaudeAnalysis: true,
verbose: true
});
console.log(`Scanned: ${result.threadsScanned}`);
console.log(`Insights: ${result.insightsFound}`);
console.log(`Cost: $${result.costUsd}`);
startScheduledAgent(schedule?, options?): void
Start a continuously running scheduled agent.
import { startScheduledAgent } from './agent/runner';
// Daily at 9 AM
startScheduledAgent('0 9 * * *', { verbose: true });
// Every 6 hours
startScheduledAgent('0 */6 * * *');
Types
ThreadData
interface ThreadData {
extractedAt: string;
post: RedditPost;
metrics: ThreadMetrics;
topComments: RedditComment[];
allComments: RedditComment[];
}
RedditPost
interface RedditPost {
id: string;
title: string;
selftext: string;
score: number;
upvoteRatio: number;
numComments: number;
author: string;
subreddit: string;
permalink: string;
url: string;
createdUtc: number;
flair?: string;
}
MarketInsight
interface MarketInsight {
id: string;
threadUrl: string;
subreddit: string;
extractedAt: string;
painPoints: PainPoint[];
opportunities: Opportunity[];
competitorMentions: CompetitorMention[];
buyingSignals: BuyingSignal[];
keyQuotes: KeyQuote[];
summary: string;
}
GoldmineScore
interface GoldmineScore {
url: string;
title: string;
score: number;
numComments: number;
upvoteRatio: number;
goldmineScore: number;
subreddit: string;
}
Python Scripts
find_goldmine_threads.py
python3 find_goldmine_threads.py <subreddit> [--query "search terms"]
# Examples
python3 find_goldmine_threads.py SaaS
python3 find_goldmine_threads.py entrepreneur --query "frustrating"
reddit_extractor.py
python3 reddit_extractor.py <url> [--json] [--prompt]
# Examples
python3 reddit_extractor.py "https://reddit.com/r/..."
python3 reddit_extractor.py "https://reddit.com/r/..." --json > data.json
python3 reddit_extractor.py "https://reddit.com/r/..." --prompt > for_claude.txt
Error Handling
All async functions may throw errors. Wrap in try/catch:
try {
const thread = await fetchThread(url);
} catch (error) {
if (error.message.includes('403')) {
console.error('Reddit blocked request - try again later');
} else if (error.message.includes('Empty response')) {
console.error('Thread may be deleted or private');
} else {
throw error;
}
}