ScavioScavio

Reddit API

The Reddit API lets you search Reddit posts or retrieve a full post with its threaded comments. Both endpoints return structured JSON with subreddit, author, score, flair, awards, and media fields. Use it to power discussion-aware agents, brand monitoring, sentiment analysis, or RAG pipelines that need community-sourced context.

Response time: 5-15 seconds. Reddit requests are significantly slower than our other platforms because they use JavaScript rendering and premium residential proxies to get fresh results. Set a client timeout of at least 30 seconds, show a skeleton or progress indicator, and consider streaming or async UX patterns.

Endpoints

EndpointCreditsDescription
POST /api/v1/reddit/search2Search Reddit posts by query, sort, and pagination cursor
POST /api/v1/reddit/post2Get a full post with threaded comments by Reddit post URL

Authentication

HeaderValueRequired
AuthorizationBearer YOUR_API_KEYYes
Content-Typeapplication/jsonYes

Post Search

Bash
POST https://api.scavio.dev
/api/v1/reddit/search

Search Reddit posts across all of Reddit. Returns post metadata including title, URL, subreddit, author, timestamp, and NSFW flag. Supports pagination via a cursor token.

Request Body

ParameterTypeDefaultDescription
querystring--Required. Search query (1-500 chars).
sortstringrelevanceSort order. One of: relevance, hot, top, new, comments
cursorstring--Pagination token from the previous response's nextCursor field.

Example

curl -X POST 'https://api.scavio.dev
/api/v1/reddit/search' \
  -H 'Authorization: Bearer sk_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "best python web frameworks 2026",
    "sort": "new"
  }'

Response Example

JSON
{
  "data": {
    "searchQuery": "best python web frameworks 2026",
    "totalResults": 14,
    "nextCursor": "eyJjYW5kaWRhdGVzX3JldH...",
    "posts": [
      {
        "position": 0,
        "id": "t3_1smb9du",
        "title": "FastAPI vs Django in 2026 -- what the teams are actually using",
        "url": "https://www.reddit.com/r/Python/comments/1smb9du/fastapi_vs_django/",
        "subreddit": "Python",
        "author": "python_dev",
        "timestamp": "2026-04-15T16:34:40.389000+0000",
        "nsfw": false
      }
    ]
  },
  "response_time": 5200,
  "credits_used": 2,
  "credits_remaining": 498
}

Pagination

To fetch the next page, pass the nextCursor value from the previous response as the cursor parameter in your next request. When nextCursor is null, there are no more results.

Post Detail

Bash
POST https://api.scavio.dev
/api/v1/reddit/post

Fetch a full Reddit post by its URL, including the post body, metadata, and full threaded comment tree. Comments include a depth field you can use to reconstruct the thread hierarchy.

Request Body

ParameterTypeDefaultDescription
urlstring--Required. Full Reddit post URL (e.g. https://www.reddit.com/r/Python/comments/1smb9du/fastapi_vs_django/).

Example

curl -X POST 'https://api.scavio.dev
/api/v1/reddit/post' \
  -H 'Authorization: Bearer sk_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://www.reddit.com/r/Python/comments/1smb9du/fastapi_vs_django/"
  }'

Response Example

JSON
{
  "data": {
    "post": {
      "id": "t3_1smb9du",
      "title": "FastAPI vs Django in 2026 -- what the teams are actually using",
      "body": "After a year of running both in production...",
      "url": "https://www.reddit.com/r/Python/comments/1smb9du/fastapi_vs_django/",
      "contentUrl": "https://www.reddit.com/r/Python/comments/1smb9du/fastapi_vs_django/",
      "subreddit": "Python",
      "author": "python_dev",
      "score": 842,
      "upvoteRatio": 0.97,
      "numComments": 214,
      "timestamp": "2026-04-15T16:34:40.389000+0000",
      "flair": "Discussion",
      "nsfw": false,
      "awards": []
    },
    "comments": [
      {
        "id": "t1_lxs9a0k",
        "author": "senior_py",
        "body": "We moved to FastAPI for the API surface and kept Django for admin...",
        "score": 312,
        "depth": 0,
        "timestamp": "2026-04-15T17:02:11.000000+0000",
        "parentId": "t3_1smb9du"
      },
      {
        "id": "t1_lxsa1b2",
        "author": "django_dev",
        "body": "Django ORM is still unmatched for anything with relational depth.",
        "score": 178,
        "depth": 1,
        "timestamp": "2026-04-15T17:15:42.000000+0000",
        "parentId": "t1_lxs9a0k"
      }
    ]
  },
  "response_time": 8900,
  "credits_used": 2,
  "credits_remaining": 496
}

Reconstructing the Comment Tree

Comments are returned as a flat array in traversal order. Use the depth field (0-indexed) for visual indentation, or reconstruct the full tree via each comment's parentId. Top-level replies have parentId equal to the post id (e.g. t3_…); nested replies have parentId equal to another comment id (e.g. t1_…).

url vs contentUrl

url is the canonical Reddit permalink for the post. contentUrl is the URL Reddit renders in the post body -- for link posts this will be the external article, for self/text posts it is the same as url, and for image/video posts it is the media URL on i.redd.it or v.redd.it.

Response Format

Both endpoints return a consistent response wrapper:

FieldTypeDescription
dataobject | nullThe response payload. null if the request failed upstream. Search returns {searchQuery, totalResults, nextCursor, posts}; post returns {post, comments}.
response_timenumberServer-side response time in milliseconds
credits_usednumberNumber of credits consumed (always 2 for Reddit endpoints)
credits_remainingnumberCredits remaining in your current billing period

Error Responses

StatusDescription
400Invalid request body -- missing query / url, bad cursor, or unsupported sort value
401Unauthorized -- missing or invalid API key
429Rate or usage limit exceeded for your plan
502Upstream error -- retry after a short delay
503Upstream unavailable -- retry later
504Upstream timeout -- Reddit requests can take 5-15 seconds; retry with a longer client timeout

See Errors for the full error reference and retry best practices.

Related