Reddit

Overview

Reddit is a social news platform with user-driven communities (subreddits), offering content sharing, discussions, and viral marketing opportunities for brands. With the Reddit integration in SquadOS, your agents can create posts, comment, search subreddits, retrieve content, and interact with communities directly, without manual intervention.

• Official website: https://www.reddit.com/
• Composio documentation: docs.composio.dev/toolkits/reddit

Authentication

This tool uses OAuth 2.0 (OAUTH2) to connect.

Field	Required	Description
—	—	No manual credentials. Authentication is handled via OAuth 2.0 through Composio’s secure page.

How to connect in SquadOS

1. Go to Tools in the side menu (/admin/tools).
2. Open the Available tab and search for Reddit.
3. Click the card to open the details and hit Connect.
4. You’re taken to the secure connection page hosted by Composio, where you authorize access to your Reddit account (OAuth 2.0).
5. Once done, you’re sent back to SquadOS with the account connected and the tool available to agents. (Connection-flow details in Organization Tools.)

Available actions

Create a Reddit post

REDDIT_CREATE_REDDIT_POST

Creates a new text or link post on a specified, existing Reddit subreddit, optionally applying a flair. Immediately publishes publicly visible content — confirm subreddit, title, and body with the user before executing. Posts may be silently removed post-submission by automoderator or subreddit rules (errors: SUBMIT_VALIDATION_BODY_BLACKLISTED_STRING, POST_GUIDANCE_VALIDATION_FAILED); verify visibility via the returned permalink. Rapid consecutive calls trigger RATELIMIT errors with cooldown hints.

Input parameters

Name	Type	Required	Description
url	string	No	The URL for a ‘link’ post. Required if kind is ‘link’.
kind	string (“link” | “self”)	No	The type of the post. Use ‘self’ for a text-based post (when providing ‘text’) or ‘link’ for a post that links to an external URL (when providing ‘url’). If omitted, it is automatically inferred: ‘self’ when ‘text’ is provided, ‘link’ when ‘url’ is provided.
text	string	No	The markdown-formatted text content for a ‘self’ post. Required if kind is ‘self’. Body must not exceed ~40,000 characters.
title	string	Yes	The title of the post. Must be 300 characters or less.
flair_id	string	No	ID of the post flair template (UUID format). Must be a valid flair template ID that exists for this specific subreddit. To get valid flair IDs, first use LIST_SUBREDDIT_POST_FLAIRS action for the target subreddit. Do not pass generic strings like ‘general’ or ‘news’ - these are not universal flair IDs. Some subreddits enforce mandatory flair; omitting or providing an invalid ID returns SUBMIT_VALIDATION_FLAIR_REQUIRED.
subreddit	string	Yes	The name of the subreddit (without the ‘r/’ prefix) where the post will be submitted.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Delete Reddit comment

REDDIT_DELETE_REDDIT_COMMENT

Deletes a Reddit comment, identified by its fullname ID, if it was authored by the authenticated user. Deletion is permanent and irreversible.

Input parameters

Name	Type	Required	Description
id	string	Yes	The full ‘thing ID’ (fullname, e.g., ‘t1_c0s4w1c’) of the comment to delete; typically starts with ‘t1_’.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Delete a Reddit post

REDDIT_DELETE_REDDIT_POST

Permanently and irreversibly deletes a Reddit post by its ID. Confirm with the user before calling. Only works on posts authored by the authenticated account; attempting to delete another user’s post will fail.

Input parameters

Name	Type	Required	Description
id	string	Yes	The full name (fullname) of the Reddit post to be deleted. This ID must start with ‘t3_’ followed by the post’s unique base36 identifier.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Edit comment or post

REDDIT_EDIT_REDDIT_COMMENT_OR_POST

Edits the body text of the authenticated user’s own existing comment or self-post on Reddit; cannot edit link posts or titles.

Input parameters

Name	Type	Required	Description
text	string	Yes	The new raw markdown text for the body of the comment or self-post.
thing_id	string	Yes	The full name (fullname) of the comment or self-post to edit. This is a combination of a prefix (e.g., ‘t1_’ for comment, ‘t3_’ for post) and the item’s ID.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Get Reddit listing by sort

REDDIT_GET

Tool to retrieve a listing of Reddit posts sorted by the specified criteria (hot, new, top, etc.). Use when you need to get posts from the Reddit front page or all of Reddit with a specific sort order. Supports pagination and time filtering for top/controversial sorts.

Input parameters

Name	Type	Required	Description
show	string	No	The string ‘all’ to show all posts including filtered ones.
sort	string	Yes	The sorting method for results. Valid values: hot, new, top, rising, controversial, best. Note: ‘random’ is NOT supported here - use the GET_RANDOM action instead.
after	string	No	Fullname of a thing for pagination (loads posts after this item).
count	integer	No	A positive integer representing the number of items already seen (default: 0).
limit	integer	No	The maximum number of items desired (default: 25, maximum: 100).
before	string	No	Fullname of a thing for pagination (loads posts before this item).
time_filter	string	No	Time filter for ‘top’ and ‘controversial’ sorts. Valid values: hour, day, week, month, year, all.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Get controversial posts from all subreddits

REDDIT_GET_CONTROVERSIAL_POSTS

Tool to retrieve controversial posts from all subreddits with time filters. Use when you need to find the most controversial posts across Reddit from a specific time period (hour, day, week, month, year, or all-time). Returns a paginated listing of posts ranked by controversy within the specified time frame.

Input parameters

Name	Type	Required	Description
t	string (“hour” | “day” | “week” | “month” | “year” | “all”)	No	Time filter for ranking controversial posts. Specifies the time period: ‘hour’, ‘day’, ‘week’, ‘month’, ‘year’, or ‘all’ (default).
after	string	No	Fullname of a thing to use as anchor for pagination. Returns results that occur after this fullname in the listing.
limit	integer	No	Maximum number of controversial posts to return. Default is 25, maximum is 100.
before	string	No	Fullname of a thing to use as anchor for pagination. Returns results that occur before this fullname in the listing.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Get user preferences

REDDIT_GET_ME_PREFS

Tool to retrieve preference settings of the logged in user. Use when you need to check user preferences or settings.

Input parameters

Name	Type	Required	Description
fields	string	No	A comma-separated list of preference fields to return. If not specified, all preference fields are returned. Supported fields include: threaded_messages, hide_downs, hide_ups, activity_relevant_ads, nightmode, compress, beta, media, media_preview, label_nsfw, over_18, search_include_over_18, hide_ads, email_messages, email_digests, monitor_mentions, hide_from_robots, profile_opt_out, public_votes, lang, theme_selector, min_comment_score, min_link_score, accept_pms, show_link_flair, show_trending, private_feeds, research, ignore_suggested_sort, domain_details, legacy_search, live_orangereds, highlight_controversial, no_profanity, email_unsubscribe_all, in_redesign_beta, allow_clicktracking, show_twitter, store_visits, threaded_modmail, enable_default_themes, geopopular, show_stylesheets, show_promote, organic, collapse_read_messages, show_flair, mark_messages_read, top_karma_subreddits, newwindow, video_autoplay, credit_autorenew, clickgadget, use_global_defaults, other_theme, num_comments, numsites, and g.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Get new posts from subreddit (Deprecated)

REDDIT_GET_NEW

DEPRECATED: Use RetrieveRedditPost instead. Tool to retrieve newest posts from a subreddit sorted by creation time. Use when you need to find the most recently submitted posts to discover fresh content. Returns a paginated listing of posts ranked by newest first.

Input parameters

Name	Type	Required	Description
after	string	No	Fullname of a thing to use as anchor for pagination. Returns results that occur after this fullname in the listing.
count	integer	No	Used by Reddit to number listings after the first page for pagination. Represents the number of items already seen.
limit	integer	No	Maximum number of new posts to return. Default is 25, maximum is 100.
before	string	No	Fullname of a thing to use as anchor for pagination. Returns results that occur before this fullname in the listing.
subreddit	string	Yes	Subreddit name (without ‘r/’ prefix). Must contain only letters, numbers, and underscores. No spaces or special characters allowed. Case-insensitive.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Get random Reddit post

REDDIT_GET_RANDOM

Tool to retrieve a random public Reddit post from any subreddit. Use when you want to discover serendipitous content or need a random post for testing or entertainment purposes.

Input parameters

Name	Type	Required	Description
subreddit	string	No	Name of the subreddit to get a random post from. If not specified, returns a random post from all of Reddit. Do not include ‘r/’ prefix.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Get user information

REDDIT_GET_REDDIT_USER_ABOUT

Retrieves information about a specified Reddit user account, including karma scores and gold status. Use when you need to get profile information for any public Reddit user.

Input parameters

Name	Type	Required	Description
username	string	Yes	The name of an existing Reddit user to retrieve information about. Do not include ‘u/’ prefix. Use ‘me’ to get information about the currently authenticated user.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Get top posts from subreddit

REDDIT_GET_R_TOP

Tool to retrieve top-rated posts from a subreddit with time filters. Use when you need to find the most popular posts from a specific time period (hour, day, week, month, year, or all-time). Returns a paginated listing of posts ranked by score within the specified time frame.

Input parameters

Name	Type	Required	Description
t	string (“hour” | “day” | “week” | “month” | “year” | “all”)	No	Time filter for ranking top posts. Specifies the time period for top posts: ‘hour’, ‘day’, ‘week’, ‘month’, ‘year’, or ‘all’ (default).
show	string	No	Display filtering option. Use ‘all’ to return items that would normally be omitted (e.g., posts you have hidden).
after	string	No	Fullname of a thing to use as anchor for pagination. Returns results that occur after this fullname in the listing.
count	integer	No	Used by Reddit to number listings after the first page for pagination. Represents the number of items already seen.
limit	integer	No	Maximum number of top posts to return. Default is 25, maximum is 100.
before	string	No	Fullname of a thing to use as anchor for pagination. Returns results that occur before this fullname in the listing.
sr_detail	boolean	No	Expand subreddits detail in response. Set to true to get more detailed subreddit information.
subreddit	string	Yes	Subreddit name (without ‘r/’ prefix). Must contain only letters, numbers, and underscores. No spaces or special characters allowed. Case-insensitive.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Get OAuth scopes

REDDIT_GET_SCOPES

Tool to retrieve all available OAuth scopes supported by the Reddit API. Use when you need to understand what permissions are available or check scope definitions.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Get subreddit rules

REDDIT_GET_SUBREDDIT_RULES

Fetch the explicit posting rules for a subreddit to ensure compliance before posting or commenting. Use when you need to verify content meets community guidelines or explain subreddit requirements to users.

Input parameters

Name	Type	Required	Description
raw_json	boolean	No	If True, prevents HTML encoding of special characters in rule descriptions. Recommended to set to True for cleaner text output.
subreddit	string	Yes	Name of the subreddit (without ‘r/’ prefix) for which to retrieve posting rules.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Search subreddits

REDDIT_GET_SUBREDDITS_SEARCH

Tool to search subreddits by title and description. Use when you need to find subreddits matching a specific topic or keyword. Returns a paginated listing of subreddits with their details including subscribers, descriptions, and other metadata.

Input parameters

Name	Type	Required	Description
q	string	Yes	A search query term to search subreddit titles and descriptions. Use specific keywords to find relevant subreddits.
show	string	No	The string ‘all’ to show all subreddits including those the user might have filtered.
sort	string (“relevance” | “activity”)	No	Sort order for the search results. ‘relevance’ sorts by relevance to the query (default). ‘activity’ sorts by subreddit activity.
after	string	No	Fullname of a thing - pagination cursor for the next page. Use the ‘after’ value from the previous response to get the next set of results.
count	integer	No	A positive integer (default: 0) representing the number of items already seen in previous pages. Used for pagination tracking.
limit	integer	No	The maximum number of subreddits to return. Default is 25. Maximum allowed value is 100.
before	string	No	Fullname of a thing - pagination cursor for the previous page. Use the ‘before’ value from the previous response to get the previous set of results.
sr_detail	boolean	No	Expand subreddits with additional details. Set to true to get more detailed information about each subreddit.
show_users	boolean	No	Boolean value to include user results in the search. Set to true to include users matching the search query.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Get user flair

REDDIT_GET_USER_FLAIR

Fetches the list of user flair assignments for a given subreddit. Returns paginated results with user flair details. Returned flair_id values are scoped to the specific subreddit and must not be reused across different subreddits.

Input parameters

Name	Type	Required	Description
after	string	No	User ID to use as the anchor for fetching the next page of results. Use the ‘next’ value from a previous response.
limit	integer	No	Maximum number of user flair entries to return per page. Reddit default is 25, maximum is 1000.
before	string	No	User ID to use as the anchor for fetching the previous page of results. Use the ‘prev’ value from a previous response.
subreddit	string	Yes	Name of the subreddit (e.g., ‘pics’, ‘gaming’) for which to retrieve user flair assignments. Do not include ‘r/’ prefix or URL paths — bare name only.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Check username availability

REDDIT_GET_USERNAME_AVAILABLE

Tool to check whether a username is available for registration on Reddit. Use when you need to verify if a username can be used to create a new account.

Input parameters

Name	Type	Required	Description
user	string	Yes	The username to check for availability. Must be a valid, unused username string. Usernames are case-insensitive and must be between 3-20 characters.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

List subreddit post flairs

REDDIT_LIST_SUBREDDIT_POST_FLAIRS

List available link/post flairs for a subreddit (including flair_template_id) so posts can satisfy flair-required validation. Use when you need to discover valid flair IDs before creating a post in a subreddit that requires flair. Note: Reddit may return empty or deny access if the authenticated user cannot set link flair and is not a moderator.

Input parameters

Name	Type	Required	Description
subreddit	string	Yes	The name of the subreddit (without ‘r/’ prefix) for which to retrieve available post/link flairs.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Post a comment

REDDIT_POST_REDDIT_COMMENT

Posts a comment on Reddit, replying to an existing submission (post) or another comment. Fails if the target thread is locked, archived, or restricted — verify thread state beforehand. Rapid successive calls trigger Reddit RATELIMIT errors with explicit cooldown hints (e.g., ‘take a break for 9 minutes’); honor the specified wait before retrying. A successful API response does not guarantee public visibility — automod or spam filters may silently remove the comment. Publishes immediately and publicly; confirm target and text before executing.

Input parameters

Name	Type	Required	Description
text	string	Yes	REQUIRED. The raw Markdown text of the comment to be submitted. This field must be provided and cannot be empty.
thing_id	string	Yes	REQUIRED. The ID of the parent post (link) or comment, prefixed with ‘t3_’ for a post (e.g., ‘t3_10omtdx’) or ‘t1_’ for a comment (e.g., ‘t1_h2g9w8l’). This field must be provided.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Retrieve Comments for a Post

REDDIT_RETRIEVE_POST_COMMENTS

Retrieves all comments for a Reddit post given its base-36 article ID. Response is a two-element listings array: post metadata in listings[0]; comments in listings[1].data.children with text at each [].data.body and nested replies under each comment’s replies field. Replies require recursive traversal to capture full discussion. Large, locked, or archived threads may return truncated trees or more placeholders rather than full results. Filter out comments where body is [deleted] or [removed]; use parent_id to reconstruct conversation flow. No time-filter parameter — compare created_utc against a UTC cutoff to filter by date.

Input parameters

Name	Type	Required	Description
article	string	Yes	Base-36 ID of the Reddit post (e.g., ‘q5u7q5’), typically found in the post’s URL and not including the ‘t3_’ prefix.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Retrieve posts from subreddit

REDDIT_RETRIEVE_REDDIT_POST

Retrieves posts from a specified, publicly accessible subreddit. Responses nest post data under data.children[].data; inspect the structure before parsing. Pagination uses a data.after cursor; deduplicate across pages by post id. No built-in date filtering; compare created_utc (Unix seconds, UTC) client-side. Rate limit: ~1–2 requests/second; back off on HTTP 429.

Input parameters

Name	Type	Required	Description
sort	string (“hot” | “new” | “top” | “rising” | “controversial”)	No	Sort order for posts. Options: ‘hot’ (default, most active posts), ‘new’ (newest first), ‘top’ (highest scoring), ‘rising’ (trending posts), ‘controversial’ (most controversial).
subreddit	string	Yes	The name of the subreddit from which to retrieve posts (e.g., ‘popular’, ‘pics’). Do not include ‘r/’. Subreddit names must be 3-21 characters and can only contain letters, numbers, and underscores.
max_results	integer	No	The maximum number of posts to return. Default is 5. Set to 0 to retrieve the maximum allowed by the Reddit API (100 posts). Valid range: 0-100.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Retrieve specific comment or post

REDDIT_RETRIEVE_SPECIFIC_COMMENT

Retrieves detailed information for a single Reddit comment or post using its fullname. Returns only the specified item, not surrounding thread context; use REDDIT_RETRIEVE_POST_COMMENTS for full discussion retrieval. Deleted, removed, or quarantined items may return empty or partial payloads.

Input parameters

Name	Type	Required	Description
id	string	Yes	Reddit fullname identifier. Format: type prefix (t1_ for comments, t3_ for posts) followed by a base36 ID. Examples: ‘t1_abc123’, ‘t3_1abc2de’. Note: Share URL tokens from reddit.com/r/…/s/… links are NOT valid fullnames and cannot be used directly. Note: REDDIT_RETRIEVE_POST_COMMENTS expects the bare base-36 ID without the t3_ prefix, unlike this tool.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Search across subreddits

REDDIT_SEARCH_ACROSS_SUBREDDITS

Searches Reddit for posts/comments using a query. Results nested under data.children[i].data (kind t3 for posts); a posts array may also appear — inspect actual response path. No native time-range filter; compare created_utc (Unix epoch, UTC) client-side for recency filtering. Empty children is a valid no-results outcome. Key post fields: score, num_comments, created_utc, permalink. Rate limit: ~1–2 requests/sec; HTTP 429 indicates throttling.

Input parameters

Name	Type	Required	Description
sort	string (“relevance” | “hot” | “new” | “top” | “comments”)	No	The criterion for sorting search results. ‘relevance’ (default) sorts by relevance to the query. ‘hot’ sorts by trending posts with recent upvotes and activity. ‘new’ sorts by newest first. ‘top’ sorts by highest score (typically all-time). ‘comments’ sorts by the number of comments.
after	string	No	Pagination cursor to fetch the next page of results. Use the after value from the previous response to get subsequent results.
limit	integer	No	The maximum number of search results to return. Default is 5. Maximum allowed value is 100. Paginate beyond the first page using the after cursor from data.after in the response; deduplicate results across pages by post id.
before	string	No	Pagination cursor to fetch the previous page of results. Use the before value from the previous response to get preceding results.
restrict_sr	boolean	No	If True (default), confines the search to posts and comments within subreddits. If False, the search scope is broader and may include matching subreddit names or other Reddit entities.
search_query	string	Yes	The search query string. Supports Reddit search operators: ‘title:’, ‘author:’, ‘subreddit:’, ‘url:’, ‘site:’, ‘flair:’, ‘self:yes/no’, ‘nsfw:yes/no’, and boolean operators (AND, OR, NOT). Raw URLs (starting with http:// or https://) are not allowed - use the ‘url:’ or ‘site:’ operators instead (e.g., ‘url:example.com’ to find posts linking to that domain).

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Enable or disable inbox replies

REDDIT_TOGGLE_INBOX_REPLIES

Enable or disable inbox replies for a submission or comment. Use when you want to control whether you receive inbox notifications for replies to your own posts or comments.

Input parameters

Name	Type	Required	Description
id	string	Yes	The fullname of a thing created by the user. Must be prefixed with the thing type (e.g., ‘t3_’ for a submission/post, ‘t1_’ for a comment). Example: ‘t3_abc123’ for a post.
state	boolean	Yes	Boolean value to enable or disable inbox replies. Set to true to enable receiving inbox notifications when users reply to this thing, or false to disable inbox notifications.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.