Reddit API endpoint
Searches public Reddit content and returns public post entries. 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/searchQuery parameters: q is required. subreddit is optional and restricts search to one community. sort is optional and must be one of relevance, hot, new, top, or comments; it defaults to relevance. 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 | 2025-05-04 to 2026-10-04 |
| created | 20 | 2025-05-04 to 2026-10-04 |
| selftext | 20 | |
| source_feed_url | 20 | reddit.com |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| q | string | Yes | Search keywords | gpt | |
| subreddit | string | No | Restrict search to a subreddit name, without r/ | ||
| sort | string | No | Sort: relevance, hot, new, top, or comments Allowed values: relevance, hot, new, top, comments. | ||
| time | string | No | Time window for top/comments sorts: 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/search?q=gpt&sort=relevance&time=hour&limit=10" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"query": "gpt",
"subreddit": "OpenAI",
"sort": "relevance",
"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/search?q=gpt&restrict_sr=on&sort=relevance"
}
],
"pagination": {
"limit": 25,
"after": "t3_1abcxyz"
},
"source": {
"type": "feed",
"url": "https://www.reddit.com/r/OpenAI/search?q=gpt&restrict_sr=on&sort=relevance"
}
}
}Request schema
No body schema
Response schema
#/definitions/reddit.searchResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | reddit.SearchResponse | 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 matching the search. | |||
| 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.query | string | No | openai | Search query that was run. | ||
| data.sort | string | No | relevance | Sort order that was applied, for example `relevance`. | ||
| data.source | object | No | Reddit page the results 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 the search was limited to. Omitted when the search covered all of Reddit. | ||
| 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/search?q=gpt&sort=relevance&time=hour&limit=10" \
-H "x-api-key: $CRAWLORA_API_KEY"