Reddit Leads API

Endpoint facts

Method

GET

API path

/reddit/leads

Auth

apiKey

Credits

25 credits/request

Charged on

Successful 2xx responses only

Platform

Reddit

Response schema

#/definitions/reddit.leadsResponseDoc

How this endpoint behaves

Query parameters: q is required and describes what you offer in plain language. subreddit is optional and restricts the search to one community. sort is optional and must be one of relevance, hot, new, top, or comments; it defaults to relevance. time is optional and must be one of hour, day, week, month, year, or all; it defaults to month. limit is the maximum number of leads returned, defaults to 25, and clamps to 100. min_score is the minimum buying-intent score to return, must be between 0 and 10, and defaults to 4. classifier is optional and must be one of auto, heuristic, or llm; it defaults to auto.

How scoring works: one search page of up to 100 posts is scanned per request. A deterministic prefilter always runs first. It disqualifies self-promotion, hiring posts, freelancer service adverts ([for hire], [OFFER]), revenue-milestone posts, duplicate reposts of the same title, and Title Case article headlines, then scores the survivors additively across six independent signals: explicit-ask, solution-seeking, budget, switching, manual-toil, and urgency. Buying intent is scored rather than assigned as a single exclusive label, because a post is very often a question and a lead at the same time. When classifier resolves to llm, the prefiltered candidates (up to 40) are refined in a single batched, schema-constrained model call that returns a score and a short reason for each. The prefilter is what keeps that model call roughly constant in cost per request rather than proportional to the size of the search page.

Relevance vs intent: the deterministic scorer measures whether someone is asking for something, not whether it is what you sell. Topical relevance in heuristic mode comes entirely from the Reddit search query, so keep sort on its relevance default and pass a specific q; a broad q with sort=new will return posts that read as asks but do not match your offering. The model pass is given your q and scores fit as well as intent, which is the main reason to prefer it.

Classifier modes: auto uses the model when a provider is configured, and falls back to the deterministic scorer when it is not — or when the provider call fails, in which case the response sets degraded: true so you can tell why the scores look heuristic. heuristic never calls a model. llm requires a working provider: it returns 500 when none is configured and 503 when the provider call fails, rather than silently degrading.

Credit weight: 25, matching /api/v1/extract, because the default path includes a model call. Requests sent with classifier=heuristic are charged 3.

Notable response behavior: a missing q, an invalid sort, time, or classifier value, or a min_score outside 0-10 returns 400. Reddit block pages, malformed upstream responses, and transport failures return 503. When Reddit rate limits the request, the response is 503 with a Retry-After header giving the number of seconds to wait; back off for that long and retry rather than treating the endpoint as unavailable. A model-provider failure returns 503. An empty leads array with populated stats is a valid success: it means the corpus genuinely contained no buying-intent posts above min_score, which is common in vendor-heavy or content-marketing-heavy communities. The stats object reports scanned, prefiltered, classified, and returned so the funnel is auditable.

Provider configuration: the model pass resolves its base URL from REDDIT_LEADS_LLM_BASE, then the shared OPENAI_API_BASE, OPENAI_BASE_URL, or OPENAI_API_BASE_URL, then https://api.openai.com/v1. It also reads REDDIT_LEADS_LLM_MODEL (defaults to gpt-5.4) and REDDIT_LEADS_LLM_KEY (falls back to OPENAI_API_KEY). Set REDDIT_LEADS_LLM_BASE to route this endpoint to a different provider than the rest of the deployment.

Lead search uses the same internal Redlib fallback when its native Reddit search fails. The lead response keeps its existing fields, funnel stats and credit weights; it does not add a public source field. Temporary provider, authentication, rate-limit and parser failures return 503. Provider selection is server configuration.

Sampled response

Request, 14 Oct 2026

GET /reddit/leads?classifier=heuristic&limit=20&q=crm+for+small+teams&subreddit=smallbusiness

Items in leads

1

Fields filled in every checked item

7

Shared guides

Related