@reddapi/dsh-reddit-radar

A dsh plugin that periodically scans reddapi.dev for new Reddit leads matching a one-sentence ICP description, drops the ones you've already seen, and writes the new ones to a dated markdown report in your workspace. It also forwards reddapi.dev's six read-only search/lookup MCP tools so the agent can query Reddit on demand between runs.

What it's reading

50K+	subreddits tracked
30M+	posts indexed
170M+	comments indexed
1024D	vector dimensions
5	lead types classified

Why this beats a keyword alert

Keyword alerts return thousands of irrelevant mentions and still miss the ones that matter, because people asking for what you sell rarely use your words for it. Nobody writes "I need a Reddit lead-gen tool for B2B SaaS". They write "how do you all find customers without spending on ads".

reddapi.dev matches on meaning, not spelling. Your ICP sentence is embedded into the same 1024-dimensional space as every indexed post, so a post lands in your report when it means the same thing, whether or not a single keyword overlaps. On top of that sits intent scoring: every lead is scored 0-100 on signal strength and auto-tagged with lead type, sentiment and industry, so what reaches your report is the handful of people ready to buy rather than everyone who happened to say a word. The demo set on reddapi.dev's homepage averages a 96% intent score.

That is the whole point of the scheduled scan in this plugin: you write one sentence about who you sell to, and a dated markdown file appears with the people who described that problem this week, in their own words, with a link to reply.

What it does

• Scheduled lead scan. On a cadence you pick (weekly / daily / hourly / manual), it calls reddapi.dev's /api/v1/leads with your ICP as the query, filters out leads it has already reported, and writes the rest to <outDir>/<date>.md.
• A manual tool, reddit_radar_run, that runs one pass immediately instead of waiting for the schedule.
• Six forwarded tools — reddit_semantic_search, reddit_vector_search, reddit_list_subreddits, reddit_get_subreddit, reddit_get_trends, reddit_find_leads — thin shells over reddapi.dev's own MCP endpoint, so the agent can search Reddit directly instead of only seeing scheduled digests.
• A one-line notice at the start of the next session when a run found new leads, hit a quota wall, or the API key was rejected.

Install

npm install @reddapi/dsh-reddit-radar

Then add it to your cordis.yml (see the full example below).

⚠️ Three things you must know before configuring this

1. days has to track schedule, or you'll re-scan the same week forever

The default is schedule: weekly with days: 7 — each run looks at the last 7 days of Reddit activity, and the next run is roughly 7 days later, so the scanned windows line up back-to-back.

If you tighten schedule to daily (or hourly), you must shrink days to match (days: 1 for daily). If you leave days: 7 while running daily, every single run re-scans the same rolling week — you'll see mostly leads you already reported, and burn quota re-fetching data you've already seen. days only accepts 1 | 7 | 30 | 90 (reddapi.dev's whitelist); pick the value closest to your actual cadence.

schedule	recommended days
hourly	1 (there's no <1 option — this still over-scans, use sparingly)
daily	1
weekly	7 (default)
manual	whatever window makes sense when you trigger reddit_radar_run

2. Free-tier quota is shared with MCP tool calls — 3 per 7 days, not per month

Free reddapi.dev accounts now have full API access, same as every paid tier, so a free account's key works with /api/v1/leads and this plugin out of the box — no subscription required.

What free accounts get instead of a blanket block is a small, shared quota: 3 requests per fixed 7-day window — the window resets every Thursday 00:00 UTC. This is not a calendar month and not a rolling window. That pool is shared across the reddapi.dev website search UI, every /api/v1/* endpoint, /api/leads, and MCP tools/call — i.e. one counter for everything you do with a free key.

At the default weekly / days: 7 cadence, radar's own scheduled scan consumes 1 request per window. What the rest of the pool goes to is entirely up to you — the counter does not care where a call came from.

⚠️ This is the part most likely to bite you: the six forwarded MCP tools (below) count against this same pool. MCP protocol methods — initialize, tools/list, resources/list, prompts/list — are free handshake calls and don't consume quota, but every actual tools/call does — including reddit_semantic_search, reddit_find_leads, and the other four tools this plugin forwards. If your agent calls even two or three of them in one conversation, that alone can burn through the entire 3-per-week free allowance. The next scheduled radar run in that window will then fail with a 429 (see Troubleshooting) instead of writing a report. That is the mechanism, not a recommendation — how you spend the three requests is your call, just know that scheduled scans and ad-hoc tool calls draw down the same counter. Paid plans (Lite and above) have much larger, plan-specific monthly/daily quotas with no such shared-with-MCP collision risk — see reddapi.dev/pricing.

3. There is no "every Monday at 9am" — only a cadence tier + heartbeat

dsh 0.1.0-rc.6 doesn't give third-party plugins a cron facility. The only scheduling primitive a plugin can use is a fixed-interval timer — there's no cron expression and no wall-clock target time. (@deepseek-ai/dsh-schedule looks like it might fill that gap, but it's actually an agent-scoped, session-level "remind me" tool bound to a specific root agent's event log — not something a plugin can register a background job against.)

So schedule: weekly doesn't mean "every Monday at 09:00" — it means a cadence tier plus a persisted heartbeat: every hour (or every tick, if the tier is shorter than an hour), the plugin checks how long it's been since the last run and only runs if that's ≥ the tier's duration. Consequences:

• Restarting the host process does not trigger an extra run — the last run time is persisted and survives restarts (in the host's own storage when available, or a .state.json file in outDir otherwise).
• If the host was off for a while, the next heartbeat after startup will catch up with exactly one run (not one run per missed tick).
• The actual time-of-day a weekly run lands on will drift with whenever the host happens to be running when a tick lands ≥7 days after the last run — it is not pinned to a specific day or hour.

If you need a run at a specific time, use schedule: manual and trigger reddit_radar_run yourself (e.g. from your own external cron hitting the agent, or via dsh-schedule's session-level reminders).

Config reference

Key	Type	Default	Notes
apiKey	string	— (required)	reddapi.dev API key. Free accounts work now — log in at reddapi.dev and open /account; a key is minted automatically, no subscription needed. Free-tier quota is small and shared with MCP tool calls — see "Free-tier quota is shared with MCP tool calls" above before relying on it.
icp	string	— (required)	One sentence: what you sell and to whom. Used verbatim as the search query.
schedule	'weekly' | 'daily' | 'hourly' | 'manual'	'weekly'	'manual' registers no timer — only the reddit_radar_run tool.
days	1 | 7 | 30 | 90	7	Only consider posts from the last N days. Must track schedule — see above.
outDir	string	.dsh/reddit-radar	Where markdown reports (and the .state.json fallback) land. Relative paths resolve against the process's working directory.
maxPerRun	number	10	Max leads written per report (1–50). Leads cut by this limit can still be picked up on a later run.

Full cordis.yml example

- id: reddit-radar
  name: '@reddapi/dsh-reddit-radar'
  config:
    apiKey: rk_live_xxxxxxxxxxxxxxxx   # get one at https://reddapi.dev (Account → API Keys)
    icp: We sell a Reddit lead-gen tool to B2B SaaS founders
    schedule: weekly                  # weekly | daily | hourly | manual
    days: 7                           # 1 | 7 | 30 | 90 — keep in sync with `schedule`
    outDir: .dsh/reddit-radar
    maxPerRun: 10

Get an API key at reddapi.dev — log in and open /account; a key is minted automatically, free accounts included. See "Free-tier quota is shared with MCP tool calls" above for what a free key can realistically sustain (3 requests / 7-day window, shared with the six forwarded MCP tools) versus a paid plan's larger, unshared quota.

Plan	Price	Searches
Free	$0 forever	3 / 7 days
Lite	$19.9 /mo	500 /mo
Starter	$49 /mo	5,000 /mo
Pro	$99 /mo	15,000 /mo
Team	$249 /mo	50,000 /mo

A weekly scan costs 1 search per week, so any paid tier leaves the rest of the month's quota for the agent's own ad-hoc searches. Current figures live at reddapi.dev/pricing.

Forwarded MCP tools

These six tools are registered as thin shells that forward directly to https://reddapi.dev/api/mcp's tools/call, reusing the same apiKey from your config. Their argument schemas are pulled live from reddapi.dev's own tools/list at plugin startup — this plugin does not hardcode or duplicate them, so they can't drift out of sync with the live API:

Tool	What it does
reddit_semantic_search	Ask in plain English. An LLM step reads intent, so it handles a question the way a person would ask it.
reddit_vector_search	The same 1024D index without the LLM step: faster and cheaper, matches on meaning rather than wording. Use it when the agent already knows what it is looking for.
reddit_list_subreddits	Paginated list of tracked subreddits.
reddit_get_subreddit	Detail lookup for one subreddit.
reddit_get_trends	Trending Reddit keywords, sorted by popularity.
reddit_find_leads	One-shot lead search (same underlying endpoint the scheduled radar uses).

Each call to one of these six tools is a tools/call against reddapi.dev's MCP endpoint, which on a free account draws from the same 3-per-7-days pool as the scheduled radar scan itself — see "Free-tier quota is shared with MCP tool calls" above. initialize/tools/list (used once at plugin startup to fetch the schemas) are free protocol handshakes and don't count.

If reddapi.dev's tool list can't be fetched at startup — network hiccup, a rejected apiKey (invalid, mistyped, or revoked — not a plan-tier issue anymore, every plan including Free has API access), or reddapi.dev being briefly unreachable — these six tools are simply not registered for that session. This is silent by design past a single warning: the scheduled radar (the plugin's actual job) does not depend on them and keeps running normally either way. If you don't see these tools available, check that apiKey is valid and reddapi.dev is reachable, then reload the plugin.

Troubleshooting

401/403 and 429 mean very different things to this plugin, and it handles them very differently — don't treat them as the same "it's broken" signal.

"your reddapi.dev quota is used up" (429) — the common one on a free account

All plans, including Free, have API access now, so a correctly-configured key normally never sees a 401/403 at all. What a free account is much more likely to hit is a 429: the shared 3-per-7-days quota (see "Free-tier quota is shared with MCP tool calls" above) ran out — usually because the six forwarded MCP tools were used in the same 7-day window as the scheduled radar scan.

This plugin treats a 429 as a quota problem, not an auth error, and does not stop the timer for it. The scheduled radar keeps ticking; the next run (per your schedule cadence) will simply try again, and by the time a weekly run comes back around the 7-day quota window has normally reset anyway. Nothing needs to be reloaded or reconfigured. The on-screen notice text ("...Upgrade at reddapi.dev/pricing to resume") is shared boilerplate with paid-plan overages — on a free account, upgrading is optional, not required: waiting for the next 7-day window resets the same 3 requests for free. Upgrade only if you want the radar scan and the six MCP tools to stop competing for the same small pool.

"the configured reddapi.dev API key was rejected" (401/403) — schedule stopped

This is the notice reddit-radar shows after an actual 401 or 403 from /api/v1/leads. Unlike a 429, this plugin treats both as one auth-error outcome and deliberately stops the timer, so it doesn't keep failing forever in the background. Since every plan tier now has API access, this is essentially always a genuine credential problem, not a plan issue:

1. Check for a typo, extra whitespace, or a key that was rotated/revoked in the account dashboard.
2. Confirm the key was copied from the same reddapi.dev account you expect — /account mints one key per account.
3. Once the key is fixed, reload the plugin — the timer was torn down and won't come back on its own; a config reload re-registers it. (A 429 never requires this step — only 401/403 tears the schedule down.)

Development

npm install
npm test          # vitest, 69 cases
npm run build      # tsc -p tsconfig.build.json → dist/

The pure decision logic (which leads are new, what a run outcome means, how a report gets rendered) has no dsh or network dependency and is unit-tested in isolation; a separate suite covers the scheduling/heartbeat/tool-registration wiring against a minimal fake host; another verifies the actual build output loads under real Node ESM (not just that the build exits cleanly).