> ## Documentation Index > Fetch the complete documentation index at: https://socialquery.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Reddit media search > Search one public non-NSFW Reddit media window, with up to 25 source candidates per page. Native query matching may include related results. sort=new ignores timeframe. Date bounds filter each window without stopping unordered pagination; query-bound opaque cursors stop at 40 pages. Gallery URLs are actual images, while video files and optional audio playlists come from validated post enrichment. Failed post/avatar enrichment yields explicit partial status and null unknown fields, never an invented media URL. Reddit net score stays ext.score, not likes. Source enrichment can be cached for one hour. A nonempty fresh result costs one credit; empty filtered windows, cache hits and replays are free. Finite Redditapis and ScrapeBadger allowances do not establish sustained production capacity. Search public image, gallery and video posts with `query`. Each request examines **up to 25 native candidates**, filters to media and then applies `since` / `until`. Related results may appear because query semantics belong to Reddit's live index. NSFW content is excluded by the upstream search option. `sort` accepts `relevance` (default), `new`, `top`, or `comment_count`. `timeframe` accepts `all` (default), `day`, `week`, `month`, or `year`; it has no effect with `sort=new`. Dates accept `YYYY-MM-DD` or ISO timestamps with a timezone. Date-only bounds are inclusive UTC days. Unknown publication dates are excluded when a bound is set. Follow `next_cursor` with the same query and filters. A filtered page can be empty and still have a cursor. Date filtering never stops the search walk because relevance results are not chronological. The adapter stops after **40 pages**, exposes `stopped_at=page_limit`, and does not claim a complete Reddit archive. A null cursor with `listing_status=unknown` also does not certify exhaustive coverage. `total` is the returned page count, not an estimated global match count. Each item contains `{post, computed}`. Gallery `media_urls` contain actual image URLs; a gallery landing page is never reported as an image. Native videos expose a direct fallback file and, when available, `ext.video_hls_url` / `video_dash_url`. The fallback file may omit a separate audio track. Signed media URLs may expire. Post and author enrichment supplies avatars, upvote ratio and flair, and can be cached for **one hour**. Missing or failed enrichment sets `ext.enrichment_status=partial`, adds warning codes, and leaves unavailable fields null. Partial responses are not cached as complete API results. Reddit's net score is `ext.score`; `engagement.likes` stays null. Unknown verification, shares, deletion state and computed metrics are not inferred. A fresh **nonempty** response costs **1 credit**, including disclosed partial enrichment. Empty filtered pages, cached responses and idempotent replays cost zero. Invalid inputs and failed search requests are also uncharged. Use `X-Max-Credits: 1` and a 60-second client timeout; the shared upstream deadline is 47 seconds. This adapter combines Redditapis public media search and ScrapeBadger public enrichment. It is constrained by approved trial/existing-credit verification allowances. A successful query does not establish sustained production capacity or exhaustive search coverage. ## OpenAPI ````yaml GET /reddit/search/media openapi: 3.1.0 info: title: SocialQuery API version: '2026-10-09' description: >- Documented requests for public-source records. Inspect accepted inputs and credit amounts, then verify the selected operation before integrating preview coverage. servers: - url: https://socialquery.dev/v1 security: - apiKey: [] paths: /reddit/search/media: get: tags: - Reddit summary: Reddit Search Media description: >- Search one public non-NSFW Reddit media window, with up to 25 source candidates per page. Native query matching may include related results. sort=new ignores timeframe. Date bounds filter each window without stopping unordered pagination; query-bound opaque cursors stop at 40 pages. Gallery URLs are actual images, while video files and optional audio playlists come from validated post enrichment. Failed post/avatar enrichment yields explicit partial status and null unknown fields, never an invented media URL. Reddit net score stays ext.score, not likes. Source enrichment can be cached for one hour. A nonempty fresh result costs one credit; empty filtered windows, cache hits and replays are free. Finite Redditapis and ScrapeBadger allowances do not establish sustained production capacity. operationId: get_reddit_search_media parameters: - name: query in: query required: true example: mechanical keyboard build schema: type: string - name: sort in: query required: false schema: type: string enum: - relevance - new - top - comment_count - name: timeframe in: query required: false schema: type: string enum: - all - day - week - month - year - name: cursor in: query required: false schema: type: string - name: since in: query required: false schema: type: string - name: until in: query required: false schema: type: string - name: Cache-Control in: header required: false example: no-cache schema: type: string - name: Idempotency-Key in: header required: false example: 7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c schema: type: string - name: X-Max-Credits in: header required: false description: >- Optional nonnegative integer cap on the maximum request hold. A live request whose hold exceeds this cap returns 422 CREDIT_BUDGET_EXCEEDED before spending. Metered holds use the requested limit; cache hits and successful idempotent replays cost zero. schema: type: integer minimum: 0 responses: '200': description: >- Search one public non-NSFW Reddit media window, with up to 25 source candidates per page. Native query matching may include related results. sort=new ignores timeframe. Date bounds filter each window without stopping unordered pagination; query-bound opaque cursors stop at 40 pages. Gallery URLs are actual images, while video files and optional audio playlists come from validated post enrichment. Failed post/avatar enrichment yields explicit partial status and null unknown fields, never an invented media URL. Reddit net score stays ext.score, not likes. Source enrichment can be cached for one hour. A nonempty fresh result costs one credit; empty filtered windows, cache hits and replays are free. Finite Redditapis and ScrapeBadger allowances do not establish sustained production capacity. content: application/json: schema: allOf: - $ref: '#/components/schemas/SocialQueryResponse' - type: object properties: data: type: object properties: query: type: string items: type: array items: type: object properties: post: type: object properties: id: type: string url: type: string content: type: object properties: text: type: - string - 'null' media_urls: anyOf: - type: array items: type: string - type: 'null' thumbnail_url: type: - string - 'null' duration_seconds: type: - number - 'null' required: - text - media_urls - thumbnail_url - duration_seconds additionalProperties: false author: type: object properties: username: type: string display_name: type: string avatar_url: type: - string - 'null' verified: type: - boolean - 'null' required: - username - display_name - avatar_url - verified additionalProperties: false engagement: type: object properties: views: type: - number - 'null' likes: type: - number - 'null' comments: type: - number - 'null' shares: type: - number - 'null' saves: type: - number - 'null' required: - views - likes - comments - shares - saves additionalProperties: false flags: type: object properties: nsfw: type: - boolean - 'null' spoiler: type: - boolean - 'null' pinned: type: - boolean - 'null' deleted: type: - boolean - 'null' required: - nsfw - spoiler - pinned - deleted additionalProperties: false published_at: type: - string - 'null' ext: type: object properties: title: type: string subreddit: type: string score: type: - number - 'null' upvote_ratio: type: - number - 'null' flair: type: - string - 'null' media_kind: enum: - image - gallery - video video_hls_url: type: - string - 'null' video_dash_url: type: - string - 'null' content_language: type: - string - 'null' enrichment_status: enum: - ok - partial warnings: type: array items: type: string required: - title - subreddit - score - upvote_ratio - flair - media_kind - video_hls_url - video_dash_url - content_language - enrichment_status - warnings additionalProperties: false required: - id - url - content - author - engagement - flags - published_at - ext additionalProperties: false computed: type: object properties: engagement_rate: type: - number - 'null' language: type: - string - 'null' content_category: type: - string - 'null' estimated_reach: type: - number - 'null' required: - engagement_rate - language - content_category - estimated_reach additionalProperties: false required: - post - computed additionalProperties: false returned_count: type: integer minimum: 0 total: type: integer minimum: 0 source_count: type: integer minimum: 0 source_window_count: type: integer minimum: 0 next_cursor: type: - string - 'null' stopped_at: type: - string - 'null' listing_status: enum: - continuing - complete - truncated - unknown partial: type: boolean source: const: redditapis+scrapebadger coverage_note: type: string required: - query - items - returned_count - total - source_count - source_window_count - next_cursor - stopped_at - listing_status - partial - source - coverage_note additionalProperties: false required: - data '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '402': $ref: '#/components/responses/Error402' '403': $ref: '#/components/responses/Error403' '404': $ref: '#/components/responses/Error404' '405': $ref: '#/components/responses/Error405' '409': $ref: '#/components/responses/Error409' '422': $ref: '#/components/responses/Error422' '429': $ref: '#/components/responses/Error429' '500': $ref: '#/components/responses/Error500' '502': $ref: '#/components/responses/Error502' '503': $ref: '#/components/responses/Error503' '504': $ref: '#/components/responses/Error504' components: schemas: SocialQueryResponse: type: object required: - success - platform - endpoint - credits_used - credits_remaining - request_id - cached - data properties: success: type: boolean const: true platform: type: string endpoint: type: string credits_used: type: integer minimum: 0 credits_remaining: type: - integer - 'null' request_id: type: string cached: type: boolean data: type: object additionalProperties: true description: >- The selected operation determines the resource fields in this object. Source data can omit a metric or report it as null. SocialQueryError: type: object required: - success - platform - endpoint - credits_used - credits_remaining - request_id - cached - error properties: success: type: boolean const: false platform: type: string endpoint: type: string credits_used: type: integer minimum: 0 credits_remaining: type: - integer - 'null' request_id: type: string cached: type: boolean error: type: object required: - code - type - message - status - doc_url properties: code: type: string type: type: string message: type: string status: type: integer doc_url: type: string format: uri responses: Error400: description: Upstream rejected the request. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error401: description: Missing, expired, invalid, or revoked API key. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error402: description: Insufficient SocialQuery credits. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error403: description: Key scope or provider policy denied access. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error404: description: Endpoint or upstream resource not found. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error405: description: HTTP method is not supported. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error409: description: Idempotency conflict or request in progress. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error422: description: Invalid parameters. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error429: description: Request limit reached. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error500: description: Request processing failed. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error502: description: Upstream service failed. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error503: description: Provider or required service is unavailable. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error504: description: Upstream service timed out. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' securitySchemes: apiKey: type: apiKey in: header name: x-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.