API reference · Reddit

reddit/bulk/official-api

Integrate this model through SandBase's unified API, with production-ready schemas and examples.

APIAsyncOpen model

Production endpoint

Send your first request

OpenAI-compatible endpoint with unified authentication and usage tracking.

POSThttps://api.sandbase.ai/v1/run

Model IDreddit/bulk/official-api

Input Schema

15 parameters · 0 required · 15 optional

Parameter	Type	Required	Description
`sort`	string	Optional	How to order results. For search queries: relevance (default) gives the best matches; new/top/hot/comments also work. For subreddit feeds: hot/new/top/controversial/rising. If you pick 'relevance' with a subreddit feed, it falls back to hot. relevance and comments are only valid for searches, not subreddit feeds. · Options: relevance, hot, new, top, comments, controversial, rising · Default: "relevance" relevancehotnewtopcommentscontroversialrising
`time`	string	Optional	Limits results to posts created within the selected time window. Applies to both subreddit feeds and search queries. Use 'all' to include posts from any time. · Options: all, day, hour, month, week, year · Default: "all" alldayhourmonthweekyear
`maxItems`	integer	Optional	Maximum number of results per job. Each search query, subreddit, or URL counts as a separate job, so total output can exceed this number when you have multiple inputs. Example: 2 search queries × maxItems 25 = up to 50 posts total. · Min: 1 · Max: 100 · Default: 25
`searches`	string[]	Optional	Keywords or phrases to search for on Reddit. Each query runs independently and returns up to Max Items results. Tip: wrap a query in quotes for exact phrase matching — e.g. '"web scraping"' will only match that exact phrase, while 'web scraping' matches posts containing both words anywhere. What gets searched depends on the search type flags below. If you also provide a subreddit in Start URLs, the search is scoped to that subreddit. Otherwise it searches all of Reddit.
`startUrls`	object[]	Optional	Reddit URLs to scrape directly. Supports three URL types: • Subreddit (e.g. reddit.com/r/python/) — scrapes the subreddit feed • Post (e.g. reddit.com/r/python/comments/abc123/) — fetches that post and its comments • User (e.g. reddit.com/user/someuser/) — fetches the user profile and their recent posts Tip: combine with Search Queries to search within a specific subreddit instead of globally.
`includeNSFW`	boolean	Optional	Include NSFW (Not Safe For Work) content. · Default: false
`searchPosts`	boolean	Optional	Find posts matching the search keyword. Returns post objects with title, body, upvotes, and comment count. On by default — disable if you only want comments, communities, or users. · Default: true
`searchUsers`	boolean	Optional	Find Reddit user accounts matching the keyword. Returns user objects with karma, profile info, and account age. · Default: false
`skipComments`	boolean	Optional	When scraping a direct post URL, comments are fetched by default. Enable this to get only the post metadata without its comments. Does not affect the 'Fetch Comments for Each Post' option. · Default: false
`skipCommunity`	boolean	Optional	When scraping a subreddit feed, community metadata (member count, description, etc.) is fetched alongside posts. Enable this to skip that extra request and get only posts. · Default: true
`skipUserPosts`	boolean	Optional	When scraping a user profile, recent posts are fetched by default alongside profile info. Enable this to get only the profile metadata. · Default: false
`searchComments`	boolean	Optional	Find comments matching the search keyword. Works by fetching posts that match the keyword and then filtering their comments — this uses more API calls than post search. · Default: false
`ignorestartUrls`	boolean	Optional	Forces search-only mode — Start URLs are ignored even if provided. Useful if you have URLs saved in your input but want to run a search-only job without deleting them. · Default: false
`fetchPostComments`	boolean	Optional	When enabled, each post returned from a subreddit or keyword search will include a 'comments' array with its top-level comments. Significantly increases API usage — one extra request per post. · Default: false
`searchCommunities`	boolean	Optional	Find subreddits whose name or description matches the keyword. Returns community objects with member count, description, and URL. · Default: false

Output Schema

Field	Type	Description
`id`	string	Unique identifier for the generation task
`status`	string	Task status: pending, running, completed, failed, timeout
`model`	string	Model used for the generation
`outputs`	array	Array of output items
`outputs[].url`	string	URL of the generated artifact
`outputs[].content_type`	string	MIME type (e.g. image/png, video/mp4)
`error`	object \| null	Error details if failed, null on success
`error.type`	string	Machine-readable error type code
`error.message`	string	Human-readable error description

Async Workflow

This model uses asynchronous execution. Submit a request and poll for the result.

Submit — POST to /v1/run, receive an id
Poll — GET /v1/run/{id} until status is completed, failed, or timeout
Retrieve — Read outputs from the completed response

Code Examples

Ready-to-run snippets

# Step 1: Submit
curl -X POST https://api.sandbase.ai/v1/run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
  "model": "reddit/bulk/official-api",
  "sort": "relevance",
  "time": "all",
  "maxItems": 25,
  "includeNSFW": false,
  "searchPosts": true,
  "searchUsers": false,
  "skipComments": false,
  "skipCommunity": true,
  "skipUserPosts": false,
  "searchComments": false,
  "ignorestartUrls": false,
  "fetchPostComments": false,
  "searchCommunities": false,
  "prompt": "a beautiful sunset over mountains"
}'

# Step 2: Poll result (replace <id>)
curl https://api.sandbase.ai/v1/run/<id> \
  -H "Authorization: Bearer YOUR_API_KEY"

← Back to Reddit Official API Data