SocialScrape
Get an API key
Reddit search API
  1. Docs
  2. Reddit
  3. Reddit search API

Reddit search API

Posts across Reddit, found through DuckDuckGo's index and in DuckDuckGo's order, each filled in from Reddit with its score and counts.

GET /v1/reddit/search

GET /v1/reddit/search

Posts across Reddit, found through DuckDuckGo's index and in DuckDuckGo's order, each filled in from Reddit with its score and counts. Reddit's own search and comment search are not available.

  • Cost: 1 credit
  • Cache: Results are kept up to 30 days; send max_age_days to reuse them for free.
  • Timeout: A request still running after about 25 seconds answers 202 with a job to poll (Batch and jobs).

Parameters#

NameTypeRequiredDescription
querystringyesSearch terms. Also accepted as keyword, q.
timeframestringnoOnly posts from this window. One of day, week, month, year. Also accepted as t, time.

Every request also accepts:

  • cursor: the cursor from the previous page (Pagination).
  • trim: true for a smaller response without null fields and extra.
  • raw: true to also get the platform's original object as raw.
  • max_age_days: accept a cached result up to this many days old, for 0 credits (Caching).

Example request#

Set your key in the environment first (see Authentication).

1curl -G "https://api.socialscrape.dev/v1/reddit/search" \2  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \3  --data-urlencode "query=mechanical keyboard"

Example response#

This is a sample from a recorded response, lists and long text are shortened. Status 200.

200 OKSample response
1{2  "ok": true,3  "credits_charged": 1,4  "credits_remaining": 4999,5  "cached": false,6  "cached_at": null,7  "request_id": "req_9c85756efc6dcfd46a031c4b",8  "data": {9    "object": "list",10    "items": [11      {12        "object": "post",13        "platform": "reddit",14        "id": "16cd18h",15        "url": "https://www.reddit.com/r/mac/comments/16cd18h/which_mechanical_keyboard_to_do_you_swear_is_the/",16        "type": "text",17        "author": {18          "id": "t2_4mfou",19          "handle": "CromulentSlacker",20          "name": "CromulentSlacker",21          "url": "https://www.reddit.com/user/CromulentSlacker/",22          "avatar_url": "https://styles.redditmedia.com/t5_boygb/styles/profileIcon_snoo-nftv2_bmZ0X2VpcDE1NToxMzdfYzhkM2EzYTgzYmRlNWRhZDA2ZDQzNjY5NGUzZTIyYWMzZTY0ZDU3N180OTA4MTAw_rare_73dd5500-61fd-4b67-b514-db0fe98bd4d4-headshot.png?width=64&height=64&frame=1&aut...",23          "verified": null24        },25        "title": "Which mechanical keyboard to do you swear is the best keyboard you have ever owned?",26        "text": "I broke my current keyboard so I need a replacement. My budget is around £200. I like clicky keys like Cherry MX Blues or Model M buckling springs keyboards.",27        "published_at": "2023-09-07T11:10:33.156000Z",28        "duration_seconds": null,29        "language": null,30        "hashtags": null,31        "mentions": null,32        "stats": {33          "views": null,34          "likes": 103,35          "comments": 185,36          "shares": null,37          "saves": null,38          "dislikes": null39        },40        "media": {41          "thumbnail_url": null,42          "video_url": null,43          "audio_url": null,44          "image_urls": null,45          "width": null,46          "height": null47        },48        "song": null,49        "location": null,50        "is_pinned": null,51        "is_sponsored": null,52        "extra": {53          "award_count": 0,54          "domain": "self.mac",55          "enriched": true,56          "post_type": "text",57          "score": 103,58          "search_position": 3,59          "source": "duckduckgo",60          "subreddit": "mac",61          "subreddit_id": "t5_2qh4u",62          "upvote_ratio": 0.96396396396396463        }64      },65      {66        "object": "post",67        "platform": "reddit",68        "id": "1bv7ap4",69        "url": "https://www.reddit.com/r/keyboards/comments/1bv7ap4/please_help_me_decide_which_mechanical_keyboard_i/",70        "type": "carousel",71        "author": {72          "id": "t2_39sfg654",73          "handle": "Frick-Fracker73",74          "name": "Frick-Fracker73",75          "url": "https://www.reddit.com/user/Frick-Fracker73/",76          "avatar_url": "https://styles.redditmedia.com/t5_wzelk/styles/profileIcon_snoo5311a7ff-f36d-4fbb-89a2-6582f5e61425-headshot.png?width=64&height=64&frame=1&auto=webp&crop=64%3A64%2Csmart&s=cf40dcc7cc095a30c41fd6f78ae144443fad8d0a",77          "verified": null78        },79        "title": "Please help me decide which mechanical keyboard I should get.",80        "text": "I don’t have much experience with mechanical keyboards; the only one I have owned is the Logitech g613. I’ve been looking to get my first custom mechanical keyboard that is full size, has dedicated media buttons, is wireless via usb receive...",81        "published_at": "2024-04-03T23:04:48.200000Z",82        "duration_seconds": null,83        "language": null,84        "hashtags": null,85        "mentions": null,86        "stats": {87          "views": null,88          "likes": 38,89          "comments": 100,90          "shares": null,91          "saves": null,92          "dislikes": null93        },94        "media": {95          "thumbnail_url": "https://preview.redd.it/please-help-me-decide-which-mechanical-keyboard-i-should-get-v0-k35jdaoiicsc1.jpg?width=640&crop=smart&auto=webp&s=94c98b742e34748f4cbe7e15e0be7564ab55e6d9",96          "video_url": null,97          "audio_url": null,98          "image_urls": [99            "https://preview.redd.it/please-help-me-decide-which-mechanical-keyboard-i-should-get-v0-k35jdaoiicsc1.jpg?width=640&crop=smart&auto=webp&s=94c98b742e34748f4cbe7e15e0be7564ab55e6d9",100            "https://preview.redd.it/please-help-me-decide-which-mechanical-keyboard-i-should-get-v0-wh09bboiicsc1.jpg?width=640&crop=smart&auto=webp&s=ab15feedf48740c721de1dc07e1544ee996ed6f0",101            "https://preview.redd.it/please-help-me-decide-which-mechanical-keyboard-i-should-get-v0-g4ceyaoiicsc1.jpg?width=640&crop=smart&auto=webp&s=5115b645cace52e763ad665b108f67b4733b25ab"102          ],103          "width": null,104          "height": null105        },106        "song": null,107        "location": null,108        "is_pinned": null,109        "is_sponsored": null,110        "extra": {111          "award_count": 0,112          "domain": "reddit.com",113          "enriched": true,114          "post_type": "gallery",115          "score": 38,116          "search_position": 5,117          "source": "duckduckgo",118          "subreddit": "keyboards",119          "subreddit_id": "t5_2rm65",120          "upvote_ratio": 0.88121        }122      }123    ],124    "cursor": "eyJwIjoyLCJmIjp7InEiOiJtZWNoYW5pY2FsIGtleWJvYXJkIHNpdGU6cmVkZGl0LmNvbSIsInMiOiIxMCIsIm5leHRQYXJhbXMiOiIiLCJ2IjoibCIsIm8iOiJqc29uIiwiZGMiOiIxMSIsImFwaSI6ImQuanMiLCJ2cWQiOiI0LTI4NTc3NTk2NjUwODQ3Mzc0MTg3MTMzOTAxOTkzMzgzMjIxOTc4OCIsImtsIjoid3Qt...",125    "has_more": true,126    "parent": null127  },128  "cursor": "eyJwIjoyLCJmIjp7InEiOiJtZWNoYW5pY2FsIGtleWJvYXJkIHNpdGU6cmVkZGl0LmNvbSIsInMiOiIxMCIsIm5leHRQYXJhbXMiOiIiLCJ2IjoibCIsIm8iOiJqc29uIiwiZGMiOiIxMSIsImFwaSI6ImQuanMiLCJ2cWQiOiI0LTI4NTc3NTk2NjUwODQ3Mzc0MTg3MTMzOTAxOTkzMzgzMjIxOTc4OCIsImtsIjoid3Qt...",129  "has_more": true130}

Response#

A list of Post objects in data.items, with data.cursor and data.has_more.

See Data models for every field. The envelope around data is described in Responses.

Errors#

Failures are free: credits_charged is 0. Branch on error.code, never on the message.

CodeHTTPRetryMeaning
invalid_params400noA parameter is missing, unknown or has the wrong type.
not_found404noThe platform says this profile, post or item does not exist.

Every request can also fail with the account and platform errors listed on the Errors page.