> ## Documentation Index > Fetch the complete documentation index at: https://docs.scraperize.com/llms.txt > Use this file to discover all available pages before exploring further. # Subreddit posts > Returns a subreddit's posts as its feed shows them, about 24 per page, sorted like Reddit's own sort menu (best, hot, new, top — over a day, week, month, year or all time — or rising). Each post comes with its title, link, type (text, link, image, gallery, video …), author, time, score, upvote ratio, comment and award counts, flair, linked URL and domain, thumbnail, images (originals and previews), video (HLS and MP4 renditions, poster, length) or embed, crosspost origin, and locked / pinned / NSFW flags. Pass the returned `cursor` back (with the same subreddit) for the next page. NSFW communities return 403 (Reddit only shows them to signed-in adults). Only publicly available data is returned. > [!NOTE] > > **Cost: 1 credit** per successful request. Errors and cache hits (`cache_max_age`) are free. > [accordion] Copy for AI assistant > > Paste this into ChatGPT, Claude or your coding assistant to generate working code for this endpoint (use the copy button). > > ```text Prompt > I want to make an API call to /v1/reddit/subreddit. Here are the details: > > Endpoint: GET https://api.scraperize.com/v1/reddit/subreddit > Description: Returns a subreddit's posts as its feed shows them, about 24 per page, sorted like Reddit's own sort menu (best, hot, new, top — over a day, week, month, year or all time — or rising). Each post comes with its title, link, type (text, link, image, gallery, video …), author, time, score, upvote ratio, comment and award counts, flair, linked URL and domain, thumbnail, images (originals and previews), video (HLS and MP4 renditions, poster, length) or embed, crosspost origin, and locked / pinned / NSFW flags. Pass the returned `cursor` back (with the same subreddit) for the next page. NSFW communities return 403 (Reddit only shows them to signed-in adults). Only publicly available data is returned. > > Required Headers: > - x-api-key: Your API key > > Parameters: > - subreddit (string) [required]: The subreddit's name, with or without `r/`. > - sort (select): `best` (default), `hot`, `new`, `top` or `rising`. Ignored with a cursor — the cursor keeps its sort. > - timeframe (select): For `sort=top` only: `day` (default), `week`, `month`, `year` or `all`. > - cursor (string): The `cursor` from the previous page, to get the next one. Omit for the first page. > - cache_max_age (select): Optional. Return a cached result if one this age or newer exists — served for **0 credits** with `meta.cached=true` and `meta.cachedAt`. Otherwise a fresh scrape runs (**1 credit**) and refreshes the cache. Omit to always scrape fresh. > > Example Response: > { > "data": { > "subreddit": "programming", > "sort": "best", > "timeframe": null, > "posts": [ > { > "id": "1xpbd2s", > "url": "https://www.reddit.com/r/programming/comments/1xpbd2s/unity3d_for_net_developers_how_to_get_started/", > "title": "Unity3D for .NET Developers: How to get started", > "type": "link", > "subreddit": "programming", > "subredditId": "t5_2fwo", > "author": "Kabra___kiiiiiiiid", > "authorId": "t2_1j6eobnjdj", > "authorAvatarUrl": "https://styles.redditmedia.com/t5_dl453b/styles/profileIcon_6kthtk5a7uie1.jpg?width=64&height=64&frame=1&auto=webp&crop=64%3A64%2Csmart&s=dfe40b8baca0114e9e37f5…", > "createdAt": "2026-11-06T12:16:46.030Z", > "score": 1, > "upvoteRatio": 0.6666666666666666, > "commentCount": 0, > "awardCount": 0, > "domain": "pvs-studio.com", > "linkUrl": "https://pvs-studio.com/en/blog/posts/csharp/1424/?reddit_preview=2", > "language": "en", > "flair": null, > "text": null, > "links": [], > "imageDescription": null, > "thumbnailUrl": "https://external-preview.redd.it/aW8hH6m6-sECMeiRAElIqvkIVCV1oQa4Ib15tk2C9VY.png?width=140&height=73&auto=webp&s=23c73e0f9ddd4333760f6de8debc778df4afc8fd", > "images": [], > "video": null, > "embed": null, > "crosspostParent": null, > "isNsfw": false, > "isLocked": false, > "isStickied": false, > "isArchived": false, > "isCrosspost": false > } > ], > "count": 24, > "cursor": "eyJzIjoicHJvZ3JhbW1pbmciLCJvIjoiYmVzdCIsInQiOm51bGwsImEiOiJkRE5mTVhodGIzaGhhQSJ9", > "hasMore": true, > "fetchedAt": "2026-11-06T12:49:03.147Z" > }, > "meta": { > "requestId": "req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f", > "creditsCharged": 1, > "creditsRemaining": 4999, > "cached": false > } > } > > Please help me write code in my preferred programming language to make this API call and handle the response appropriately. Include error handling and best practices. > ``` ## OpenAPI ````yaml /api-reference/openapi.json get /v1/reddit/subreddit openapi: 3.0.3 info: title: Scraperize API version: 1.0.0 description: >- Extract public data from social media platforms as clean JSON. Endpoints are split by platform and by what they return, e.g. `GET /v1/twitter/tweet`. ## Authentication Send your API key in the `x-api-key` header (or `Authorization: Bearer `). Create keys in your dashboard. ## Credits Each successful live scrape costs **1 credit**. Credits are prepaid and never expire. ## Caching Every endpoint accepts an optional `cache_max_age` (`1d`|`3d`|`7d`|`14d`|`30d`). A cache hit within that window is returned for **0 credits**. ## Responses Success returns `{ "data": …, "meta": { "requestId", … } }`. Errors return `{ "error": { "code", "message", "requestId" } }` with a matching HTTP status. `meta` on a scrape carries `creditsCharged`, `creditsRemaining`, `cached`, and (on a hit) `cachedAt`. ## Rate limits Requests are limited per team per minute; over the limit returns `429` with a `Retry-After` header. servers: - url: https://api.scraperize.com description: Production security: - ApiKeyAuth: [] tags: - name: Twitter description: Twitter / X scraping endpoints - name: Facebook description: Facebook scraping endpoints - name: Linkme description: Linkme (link.me) scraping endpoints - name: Amazon description: Amazon (creator shop / storefront) scraping endpoints - name: Linkbio description: Linkbio (lnk.bio) scraping endpoints - name: Pillar description: Pillar (pillar.io) scraping endpoints - name: Komi description: Komi (komi.io) scraping endpoints - name: Linktree description: Linktree (linktr.ee) scraping endpoints - name: Kick description: Kick (kick.com) scraping endpoints - name: Snapchat description: Snapchat (snapchat.com) scraping endpoints - name: Telegram description: Telegram (t.me) scraping endpoints - name: LinkedIn description: LinkedIn scraping endpoints - name: Twitch description: Twitch scraping endpoints - name: TikTok description: TikTok (tiktok.com) scraping endpoints - name: Instagram description: Instagram scraping endpoints - name: Lagos Life description: Lagos Life scraping endpoints - name: Bluesky description: Bluesky (bsky.app) scraping endpoints - name: Threads description: Threads (threads.com) scraping endpoints - name: Reddit description: Reddit (reddit.com) scraping endpoints - name: Rumble description: Rumble (rumble.com) scraping endpoints - name: Truth Social description: Truth Social (truthsocial.com) scraping endpoints - name: YouTube description: YouTube (youtube.com) scraping endpoints paths: /v1/reddit/subreddit: get: tags: - Reddit summary: Subreddit posts description: >- Returns a subreddit's posts as its feed shows them, about 24 per page, sorted like Reddit's own sort menu (best, hot, new, top — over a day, week, month, year or all time — or rising). Each post comes with its title, link, type (text, link, image, gallery, video …), author, time, score, upvote ratio, comment and award counts, flair, linked URL and domain, thumbnail, images (originals and previews), video (HLS and MP4 renditions, poster, length) or embed, crosspost origin, and locked / pinned / NSFW flags. Pass the returned `cursor` back (with the same subreddit) for the next page. NSFW communities return 403 (Reddit only shows them to signed-in adults). Only publicly available data is returned. parameters: - name: subreddit in: query required: true description: The subreddit's name, with or without `r/`. schema: type: string example: programming - name: sort in: query required: false description: >- `best` (default), `hot`, `new`, `top` or `rising`. Ignored with a cursor — the cursor keeps its sort. schema: type: string enum: - best - hot - new - top - rising default: best - name: timeframe in: query required: false description: >- For `sort=top` only: `day` (default), `week`, `month`, `year` or `all`. schema: type: string enum: - all - day - week - month - year - name: cursor in: query required: false description: >- The `cursor` from the previous page, to get the next one. Omit for the first page. schema: type: string - name: cache_max_age in: query required: false description: >- Optional. Return a cached result if one this age or newer exists — served for **0 credits** with `meta.cached=true` and `meta.cachedAt`. Otherwise a fresh scrape runs (**1 credit**) and refreshes the cache. Omit to always scrape fresh. schema: type: string enum: - 1d - 3d - 7d - 14d - 30d example: 7d responses: '200': description: One page of posts (empty when the subreddit has none). content: application/json: schema: type: object properties: data: type: object properties: subreddit: type: string sort: type: string timeframe: type: string nullable: true posts: type: array items: type: object count: type: integer cursor: type: string nullable: true hasMore: type: boolean fetchedAt: type: string format: date-time meta: type: object description: >- requestId + credit/caching metadata (creditsCharged, creditsRemaining, cached, cachedAt). required: - data - meta example: data: subreddit: programming sort: best timeframe: null posts: - id: 1xpbd2s url: >- https://www.reddit.com/r/programming/comments/1xpbd2s/unity3d_for_net_developers_how_to_get_started/ title: 'Unity3D for .NET Developers: How to get started' type: link subreddit: programming subredditId: t5_2fwo author: Kabra___kiiiiiiiid authorId: t2_1j6eobnjdj authorAvatarUrl: >- https://styles.redditmedia.com/t5_dl453b/styles/profileIcon_6kthtk5a7uie1.jpg?width=64&height=64&frame=1&auto=webp&crop=64%3A64%2Csmart&s=dfe40b8baca0114e9e37f5d75845653f78aa6cce createdAt: '2026-11-06T12:16:46.030Z' score: 1 upvoteRatio: 0.6666666666666666 commentCount: 0 awardCount: 0 domain: pvs-studio.com linkUrl: >- https://pvs-studio.com/en/blog/posts/csharp/1424/?reddit_preview=2 language: en flair: null text: null links: [] imageDescription: null thumbnailUrl: >- https://external-preview.redd.it/aW8hH6m6-sECMeiRAElIqvkIVCV1oQa4Ib15tk2C9VY.png?width=140&height=73&auto=webp&s=23c73e0f9ddd4333760f6de8debc778df4afc8fd images: [] video: null embed: null crosspostParent: null isNsfw: false isLocked: false isStickied: false isArchived: false isCrosspost: false - id: 1xojg3s url: >- https://www.reddit.com/r/programming/comments/1xojg3s/openssh_on_musl_linux_has_been_letting_people/ title: >- openssh on musl linux has been letting people into password-less accounts since 2016 type: link subreddit: programming subredditId: t5_2fwo author: ThisMachineIs4 authorId: t2_cra0r authorAvatarUrl: >- https://www.redditstatic.com/avatars/defaults/v2/avatar_default_3.png createdAt: '2026-11-05T14:04:10.276Z' score: 574 upvoteRatio: 0.9541139240506329 commentCount: 77 awardCount: 0 domain: sshhole.com linkUrl: https://sshhole.com/ language: en flair: null text: null links: [] imageDescription: null thumbnailUrl: null images: [] video: null embed: null crosspostParent: null isNsfw: false isLocked: false isStickied: false isArchived: false isCrosspost: false - id: 1xf4c5d url: >- https://www.reddit.com/r/programming/comments/1xf4c5d/just_finished_my_multiplayer_system_in_c_and/ title: >- Just finished my multiplayer system in C and turns out we can support 50k players in a single server at 60hz simulation tick type: link subreddit: programming subredditId: t5_2fwo author: dechichi authorId: t2_4anbx9d9 authorAvatarUrl: >- https://styles.redditmedia.com/t5_264a50/styles/profileIcon_neu0z3t6v37f1.png?width=64&height=64&frame=1&auto=webp&crop=64%3A64%2Csmart&s=5271576083c486292ffa63c9bb51ac4b44a0bfbb createdAt: '2026-10-25T14:50:38.697Z' score: 978 upvoteRatio: 0.8631970260223049 commentCount: 205 awardCount: 0 domain: youtu.be linkUrl: https://youtu.be/imG2Tt_KOj4 language: en flair: null text: null links: [] imageDescription: null thumbnailUrl: null images: [] video: null embed: provider: YouTube url: >- https://www.youtube.com/embed/imG2Tt_KOj4?feature=oembed crosspostParent: null isNsfw: false isLocked: false isStickied: false isArchived: false isCrosspost: false count: 24 cursor: >- eyJzIjoicHJvZ3JhbW1pbmciLCJvIjoiYmVzdCIsInQiOm51bGwsImEiOiJkRE5mTVhodGIzaGhhQSJ9 hasMore: true fetchedAt: '2026-11-06T12:49:03.147Z' meta: requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f creditsCharged: 1 creditsRemaining: 4999 cached: false '400': description: Invalid or expired cursor (or one for another subreddit). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: BAD_REQUEST message: The request was invalid. requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f '401': description: Missing, invalid, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: API key required — pass it in the `x-api-key` header. requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f '402': description: Not enough credits for this request. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INSUFFICIENT_CREDITS message: >- This request costs 1 credit, but your balance is 0. Top up to continue. requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f '403': description: An NSFW (18+) subreddit — Reddit only shows it to signed-in adults. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: >- No public subreddit with that name (it may not exist, be private or banned). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: NOT_FOUND message: >- The requested content was not found (it may not exist, be deleted, or be private). requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f '422': description: Invalid query parameters (`timeframe` only goes with `sort=top`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: VALIDATION_ERROR message: Request validation failed requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f details: - path: url message: url is required '429': description: Over the per-minute rate limit — honour `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: RATE_LIMITED message: >- Rate limit exceeded — max 100 requests per 60s. Retry in ~30s. requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f '503': description: >- Temporarily unavailable — retry after `Retry-After`. `error.code` tells you why: `UPSTREAM_BLOCKED` (the source blocked this request), `EXTRACTION_FAILED` (the source returned unexpected data), `PLATFORM_UNAVAILABLE` (the source is down), or `SERVICE_UNAVAILABLE` (we are at capacity). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UPSTREAM_BLOCKED message: >- The source is temporarily unavailable. Please try again shortly. requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f components: schemas: Error: type: object properties: error: type: object properties: code: type: string example: NOT_FOUND message: type: string example: The requested content was not found. requestId: type: string example: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f details: type: array items: type: object description: Present on validation errors. required: - code - message - requestId required: - error securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Your API key. Send it in the `x-api-key` header (or `Authorization: Bearer `). Create and manage keys from your dashboard. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.