Skip to content
Shell
5.7 KB
Raw Blame

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;
  }
}