Reddit API endpoint
Returns public posts from a subreddit. A `503` with a `Retry-After` header means Reddit is temporarily throttling the request; wait that many seconds and retry. If source.type is redlib, public fields and credit weights are preserved.
/reddit/subreddit/{subreddit}/postsReturns normalized public posts from a subreddit. This is also the subreddit trend surface: use sort values hot, rising, or top to retrieve subreddit-specific trends.
Path parameters: subreddit is required and accepts a subreddit name without r/.
Query parameters: sort is optional and must be one of hot, new, top, or rising; it defaults to hot. time is optional and must be one of hour, day, week, month, year, or all when supplied. limit defaults to 25 and clamps to 100. after is an optional Reddit pagination token.
Notable response behavior: invalid subreddit names, sort values, time values, or limits return 400. Empty result sets return 404. Reddit block pages, malformed upstream responses, and transport failures return 503. When Reddit rate limits the request, the response is 503 with a Retry-After header giving the number of seconds to wait; this is a temporary throttle rather than a permanent failure, so clients should back off for that long and retry instead of treating the endpoint as unavailable. The score and comment_count fields remain in the schema but are not populated by the default feed.
When the native Reddit source fails, the service can use the internal Redlib provider. Fallback responses retain the same fields and credit weights and report source.type=redlib with a public Reddit URL. Listing cursors use the upstream JSON cursor; results remain bounded by limit. Temporary provider, authentication, rate-limit and parser failures return 503, while confirmed missing resources return 404. Provider selection is server configuration.
| Field | Filled in, of 20 checked | Values in the sample |
|---|---|---|
| id | 20 | |
| name | 20 | |
| subreddit | 20 | |
| title | 20 | |
| url | 20 | reddit.com |
| permalink | 20 | reddit.com |
| author | 20 | |
| created_utc | 20 | 2026-09-03 to 2026-10-13 |
| created | 20 | 2026-09-03 to 2026-10-13 |
| selftext | 20 | |
| source_feed_url | 20 | reddit.com |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| subreddit (path) | string | Yes | Subreddit name, without r/ | OpenAI | |
| sort | string | No | Sort: hot, new, top, or rising Allowed values: hot, new, top, rising. | ||
| time | string | No | Time window for top sort: hour, day, week, month, year, or all Allowed values: hour, day, week, month, year, all. | ||
| limit | integer | No | 25 and clamps to 100 | Maximum posts, defaults to 25 and clamps to 100 | |
| after | string | No | Reddit pagination token | ||
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/reddit/subreddit/OpenAI/posts?sort=hot&time=hour&limit=10" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"subreddit": "OpenAI",
"sort": "hot",
"posts": [
{
"id": "1abcxyz",
"name": "t3_1abcxyz",
"subreddit": "OpenAI",
"title": "OpenAI discussion thread",
"url": "https://www.reddit.com/r/OpenAI/comments/1abcxyz/openai_discussion_thread/",
"author": {
"name": "sample_user",
"profile_url": "https://www.reddit.com/user/sample_user/"
},
"created": "2024-04-19T00:00:00Z",
"selftext": "Discussion body",
"source_feed_url": "https://www.reddit.com/r/OpenAI?limit=25"
}
],
"pagination": {
"limit": 25,
"after": "t3_1abcxyz"
},
"source": {
"type": "feed",
"url": "https://www.reddit.com/r/OpenAI?limit=25"
}
}
}Request schema
No body schema
Response schema
#/definitions/reddit.subredditPostsResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | reddit.SubredditPostsResponse | No | ||||
| data.pagination | object | No | Page size and cursor for the next page. | |||
| data.pagination.after | string | No | t3_1abcxyz | Cursor to pass as the `after` parameter to fetch the next page. | ||
| data.pagination.limit | integer | No | 25 | Maximum number of items requested for this page. | ||
| data.posts | array | No | Posts in the subreddit. | |||
| data.posts[].author | object | No | Reddit user who submitted the post. | |||
| data.posts[].author.name | string | No | reddit_user | Reddit username of the author. | ||
| data.posts[].author.profile_url | string | No | https://www.reddit.com/user/reddit_user/ | URL of the author's Reddit profile page. | ||
| data.posts[].award_count | integer | No | Number of awards the post received. Set only when metrics are requested. | |||
| data.posts[].comment_count | integer | No | Number of comments on the post. Set only when metrics are requested. | |||
| data.posts[].created | string | No | 2024-04-19T00:00:00Z | Time the post was submitted, in UTC (RFC 3339). | ||
| data.posts[].created_utc | integer | No | 1713484800 | Time the post was submitted, in Unix seconds. | ||
| data.posts[].domain | string | No | self.OpenAI | Domain of the linked content, or `self.<subreddit>` for text posts. | ||
| data.posts[].estimated_downvotes | integer | No | Approximate downvote total worked out from the score and upvote ratio. Reddit does not publish exact counts. | |||
| data.posts[].estimated_upvotes | integer | No | Approximate upvote total worked out from the score and upvote ratio. Reddit does not publish exact counts. | |||
| data.posts[].flair | string | No | Discussion | Flair text attached to the post. | ||
| data.posts[].id | string | No | 1abcxyz | Reddit post id. | ||
| data.posts[].is_self | boolean | No | Whether the post is a text post rather than a link. | |||
| data.posts[].is_video | boolean | No | Whether the post is a video. | |||
| data.posts[].locked | boolean | No | Whether the post is locked against new comments. | |||
| data.posts[].name | string | No | t3_1abcxyz | Reddit full name of the post, the id prefixed with `t3_`. | ||
| data.posts[].over_18 | boolean | No | Whether the post is marked as 18+ content. | |||
| data.posts[].permalink | string | No | https://www.reddit.com/r/OpenAI/comments/1abcxyz/openai_discussion_thread/ | Reddit URL of the post's comments page. | ||
| data.posts[].score | integer | No | Net score of the post, upvotes minus downvotes as Reddit shows it. Set only when metrics are requested. | |||
| data.posts[].selftext | string | No | Discussion body | Body text of a text post. | ||
| data.posts[].source_feed_url | string | No | https://www.reddit.com/r/OpenAI/ | URL of the Reddit feed the post was read from. | ||
| data.posts[].stickied | boolean | No | Whether the post is pinned to the top of its subreddit. | |||
| data.posts[].subreddit | string | No | OpenAI | Name of the subreddit the post belongs to, without `r/`. | ||
| data.posts[].thumbnail | string | No | https://b.thumbs.redditmedia.com/example.jpg | URL of the post thumbnail image. | ||
| data.posts[].title | string | No | OpenAI discussion thread | Title of the post as submitted. | ||
| data.posts[].upvote_ratio | number | No | Share of votes that are upvotes, from 0 to 1. Set only when metrics are requested. | |||
| data.posts[].url | string | No | https://www.reddit.com/r/OpenAI/comments/1abcxyz/openai_discussion_thread/ | Reddit URL of the post. | ||
| data.posts[].vote_counts_estimated | boolean | No | Whether `estimated_upvotes` and `estimated_downvotes` are estimates. | |||
| data.sort | string | No | hot | Sort order that was applied, for example `hot`. | ||
| data.source | object | No | Reddit page the posts were read from. | |||
| data.source.type | string | No | feed | Kind of Reddit source the data was read from. | ||
| data.source.url | string | No | https://www.reddit.com/r/OpenAI/ | Reddit URL the data was read from. | ||
| data.subreddit | string | No | OpenAI | Subreddit name, without `r/`. | ||
| data.time | string | No | week | Time window that was applied, for example `week`. | ||
| msg | string | No | OK |
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 404 | Not Found | #/definitions/app.Response |
| 429 | Too Many Requests | #/definitions/app.Response |
| 503 | Service Unavailable | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/reddit/subreddit/OpenAI/posts?sort=hot&time=hour&limit=10" \
-H "x-api-key: $CRAWLORA_API_KEY"