Reddit · Social Dash Scraper Docs

Social discussions API

Live private service · intermittent proxy failures

Discover public discussions and retrieve posts with bounded comments.

The existing RSS search and browser thread contracts remain intact. Eight additive ScrapeCreators-style operations run privately with Patchright, including native comment pagination and published captions. All primary operations passed bounded production checks. The existing proxy intermittently returned HTTP 403 across destinations and later recovered without configuration changes. Production search, mixed-search and comment continuations then returned new records; one mixed page reported a posts timeout as explicit partial coverage. Public source fields and ranking can differ from the competitor.

Base URLhttp://localhost:3006

Local development example. Replace with your service origin.

Search discussions

POST/v1/search

RSS keyword discovery with optional subreddit, ranking, time-window, and result bounds. Unknown scores and metrics remain null.

Request body

Field	Type	Description
query	string	Required. Search text, 1–200 characters.
subreddits	array	Up to five subreddit names; defaults to an empty list.
sort	string	top, new, or relevance; defaults to relevance.
timeWindow	string	day, week, month, or year; defaults to month.
maxPosts	integer	1–50 posts; defaults to 25.

Request cURL

export BASE_URL="http://localhost:3006"
export API_KEY="your-service-key"

curl "$BASE_URL/v1/search" \
  -H "x-reddit-retrieval-secret: $API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"query":"meal planning","subreddits":["MealPrepSunday"],"sort":"relevance","timeWindow":"month","maxPosts":10}'

Response fields

Field	Type	Description
requestId	string	Always included.
accounting	object	Always included.
status	string	Always included.
posts	array	Always included.

Nested fields and every response variant are in the OpenAPI specification.

Retrieve threads

POST/v1/threads

Retrieve posts and nested comments from canonical HTTPS www.reddit.com post permalinks. Reaching a cap or leaving unloaded comments returns partial.

Request body

Field	Type	Description
permalinks	array	Required. 1–10 canonical HTTPS Reddit post permalinks, without query parameters or fragments.
maxCommentsPerThread	integer	1–100 comments per thread; defaults to 50.
maxDepth	integer	1–5 reply levels; defaults to 5.

Request cURL

export BASE_URL="http://localhost:3006"
export API_KEY="your-service-key"

curl "$BASE_URL/v1/threads" \
  -H "x-reddit-retrieval-secret: $API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"permalinks":["https://www.reddit.com/r/example/comments/abc123/topic/"],"maxCommentsPerThread":50,"maxDepth":3}'

Response fields

Field	Type	Description
requestId	string	Always included.
accounting	object	Always included.
status	string	Always included.
threads	array	Always included.

Nested fields and every response variant are in the OpenAPI specification.

Subreddit details

GET/v1/reddit/subreddit/details

Read community metadata, rendered rules, images, dates and weekly metrics. A matching community search header can fill a missing subscriber count; unavailable required metadata stays null with explicit partial coverage.

Query parameters

Field	Type	Description
subreddit	string	Optional.
url	string	Optional.
cache_max_age	string	Accepted only on competitor-documented routes; always fetches live. No retained cache, credit balance or billing fields.

Request cURL

export BASE_URL="http://localhost:3006"
export API_KEY="your-service-key"

curl --get "$BASE_URL/v1/reddit/subreddit/details" \
  -H "x-reddit-retrieval-secret: $API_KEY" \
  --data-urlencode "subreddit=Example"

Response fields

Field	Type	Description
requestId	string	Always included.
coverage	object	Inspect complete and reasons on every response. Source failures never masquerade as empty success.
accounting	object	Always included.
success	boolean	Always included.
status	string	success, partial, challenged or failed. error contains a sanitized machine-readable reason on failure.

Nested fields and every response variant are in the OpenAPI specification.

Subreddit posts

GET/v1/reddit/subreddit

Read one rendered page of up to 50 public posts with sort, timeframe, signed after continuation and optional trimmed records.

Query parameters

Field	Type	Description
subreddit	string	Always included.
sort	string	Default: "hot"
timeframe	string	Default: "all"
after	string	Optional.
trim	boolean \| string	Default: false
cache_max_age	string	Accepted only on competitor-documented routes; always fetches live. No retained cache, credit balance or billing fields.

Request cURL

export BASE_URL="http://localhost:3006"
export API_KEY="your-service-key"

curl --get "$BASE_URL/v1/reddit/subreddit" \
  -H "x-reddit-retrieval-secret: $API_KEY" \
  --data-urlencode "subreddit=Example" \
  --data-urlencode "sort=hot" \
  --data-urlencode "timeframe=all" \
  --data-urlencode "trim=false"

Response fields

Field	Type	Description
requestId	string	Always included.
coverage	object	Inspect complete and reasons on every response. Source failures never masquerade as empty success.
accounting	object	Always included.
success	boolean	Always included.
status	string	success, partial, challenged or failed. error contains a sanitized machine-readable reason on failure.

Nested fields and every response variant are in the OpenAPI specification.

Subreddit search

GET/v1/reddit/subreddit/search

Read public post, comment and media search sections. One signed cursor tracks each section independently and skips exhausted sections. A section failure retains usable results with explicit partial coverage. Ranking and page sizes can differ from the competitor.

Query parameters

Field	Type	Description
subreddit	string	Always included.
query	string	Default: ""
sort	string	Default: "relevance"
timeframe	string	Default: "all"
cursor	string	Optional.

Request cURL

export BASE_URL="http://localhost:3006"
export API_KEY="your-service-key"

curl --get "$BASE_URL/v1/reddit/subreddit/search" \
  -H "x-reddit-retrieval-secret: $API_KEY" \
  --data-urlencode "subreddit=Example" \
  --data-urlencode "query=planning" \
  --data-urlencode "sort=relevance" \
  --data-urlencode "timeframe=all"

Response fields

Field	Type	Description
requestId	string	Always included.
coverage	object	Inspect complete and reasons on every response. Source failures never masquerade as empty success.
accounting	object	Always included.
success	boolean	Always included.
status	string	success, partial, challenged or failed. error contains a sanitized machine-readable reason on failure.

Nested fields and every response variant are in the OpenAPI specification.

Post details

GET/v1/reddit/post

Read one post and omit comments from the response. Canonical Reddit URLs and bounded same-origin mobile share-link redirects are supported.

Query parameters

Field	Type	Description
url	string	Always included.

Request cURL

export BASE_URL="http://localhost:3006"
export API_KEY="your-service-key"

curl --get "$BASE_URL/v1/reddit/post" \
  -H "x-reddit-retrieval-secret: $API_KEY" \
  --data-urlencode "url=https://www.reddit.com/r/Example/comments/abc123/example/"

Response fields

Field	Type	Description
requestId	string	Always included.
coverage	object	Inspect complete and reasons on every response. Source failures never masquerade as empty success.
accounting	object	Always included.
success	boolean	Always included.
status	string	success, partial, challenged or failed. error contains a sanitized machine-readable reason on failure.

Nested fields and every response variant are in the OpenAPI specification.

Post comments (GET)

GET/v1/reddit/post/comments

Read a post and up to 100 comments with nested replies (depth 8). Truncation is explicit. Pass the returned signed continuation unchanged with the same post URL to retrieve native comment fragments or visible focused replies. Source POST controls retain their hidden form cursor; hidden fallback links are excluded.

Query parameters

Field	Type	Description
url	string	Always included.
cursor	string	Optional.
trim	boolean \| string	Default: false

Request cURL

export BASE_URL="http://localhost:3006"
export API_KEY="your-service-key"

curl --get "$BASE_URL/v1/reddit/post/comments" \
  -H "x-reddit-retrieval-secret: $API_KEY" \
  --data-urlencode "url=https://www.reddit.com/r/Example/comments/abc123/example/" \
  --data-urlencode "trim=false"

Response fields

Field	Type	Description
requestId	string	Always included.
coverage	object	Inspect complete and reasons on every response. Source failures never masquerade as empty success.
accounting	object	Always included.
success	boolean	Always included.
status	string	success, partial, challenged or failed. error contains a sanitized machine-readable reason on failure.

Nested fields and every response variant are in the OpenAPI specification.

Post comments (POST)

POST/v1/reddit/post/comments

The same comments operation accepts JSON when a continuation is too large for a URL. Body limit 64 KiB; cursor limit 50,000 characters. Query/body mixing and cursor batching are rejected.

Request body

Field	Type	Description
url	string	Always included.
cursor	string	Optional.
trim	boolean \| string	Default: false

Request cURL

export BASE_URL="http://localhost:3006"
export API_KEY="your-service-key"

curl "$BASE_URL/v1/reddit/post/comments" \
  -H "x-reddit-retrieval-secret: $API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"url":"https://www.reddit.com/r/Example/comments/abc123/example/","trim":false}'

Response fields

Field	Type	Description
requestId	string	Always included.
coverage	object	Inspect complete and reasons on every response. Source failures never masquerade as empty success.
accounting	object	Always included.
success	boolean	Always included.
status	string	success, partial, challenged or failed. error contains a sanitized machine-readable reason on failure.

Nested fields and every response variant are in the OpenAPI specification.

Post transcript

GET/v1/reddit/post/transcript

Read published WebVTT captions by post/share or direct v.redd.it video URL. Preserve raw_vtt and parse rolling captions into plain text. A source without published captions returns transcriptNotAvailable; challenges and failed retrieval remain failures.

Query parameters

Field	Type	Description
url	string	Always included.
language	string	Default: "en"
cache_max_age	string	Accepted only on competitor-documented routes; always fetches live. No retained cache, credit balance or billing fields.

Request cURL

export BASE_URL="http://localhost:3006"
export API_KEY="your-service-key"

curl --get "$BASE_URL/v1/reddit/post/transcript" \
  -H "x-reddit-retrieval-secret: $API_KEY" \
  --data-urlencode "url=https://v.redd.it/video123" \
  --data-urlencode "language=en"

Response fields

Field	Type	Description
requestId	string	Always included.
coverage	object	Inspect complete and reasons on every response. Source failures never masquerade as empty success.
accounting	object	Always included.
success	boolean	Always included.
status	string	success, partial, challenged or failed. error contains a sanitized machine-readable reason on failure.

Nested fields and every response variant are in the OpenAPI specification.

Global search

GET/v1/reddit/search

Search public posts or comments with signed after continuation. Comment search supports relevance/new/top and no timeframe. Unknown card fields, including post bodies and comment parent identities, remain null.

Query parameters

Field	Type	Description
query	string	Always included.
filter	string	Default: "posts"
sort	string	Default: "relevance"
timeframe	string	Default: "all"
after	string	Optional.
trim	boolean \| string	Default: false

Request cURL

export BASE_URL="http://localhost:3006"
export API_KEY="your-service-key"

curl --get "$BASE_URL/v1/reddit/search" \
  -H "x-reddit-retrieval-secret: $API_KEY" \
  --data-urlencode "query=planning" \
  --data-urlencode "filter=posts" \
  --data-urlencode "sort=relevance" \
  --data-urlencode "timeframe=all" \
  --data-urlencode "trim=false"

Response fields

Field	Type	Description
requestId	string	Always included.
coverage	object	Inspect complete and reasons on every response. Source failures never masquerade as empty success.
accounting	object	Always included.
success	boolean	Always included.
status	string	success, partial, challenged or failed. error contains a sanitized machine-readable reason on failure.

Nested fields and every response variant are in the OpenAPI specification.

Coverage & limits

Search defaults to 50 posts, maximum 50. Thread requests accept at most ten permalinks.
Search deadline: 25 seconds. Thread deadline: 140 seconds. Readiness requires a configured proxy and Chromium.
The deployed routes, authentication header, environment names, and port remain unchanged.
The worker is stateless. Product-specific research, billing, and presentation remain with the consumer.
Expanded routes: 45-second deadline, at most six document/caption attempts including one shared transient retry, 8 MiB decoded responses, 50,000 JSON nodes and depth 32.
Expanded routes share the existing browser queue so they do not exceed the configured total browser concurrency. Each operation uses a fresh logged-out proxied Patchright context; captions use bounded proxied HTTPS.
All eight expanded operations returned usable live data and were deployed together with Bluesky and Pinterest on 2026-09-11. Public-card field availability and ranking can differ from the competitor.

Errors & partial results

HTTP	Code / status	Meaning
400	invalid_request	The request failed validation.
401	invalid_request	The internal service secret is invalid.
503	upstream_error / breaker_open	Proxy unavailable or thread retrieval temporarily paused.
502	upstream_error	Retrieval failed.
504	timeout	The deadline expired; available results are retained.
200	partial / challenged	Inspect status and failure even when HTTP succeeds.