Search Reddit comments
Searches Reddit's COMMENT index directly, so a phrase that only ever appears three levels deep inside someone's reply is reachable in one call. Every other comment surface on this API needs a post you have already found; this one does not. Each hit arrives with its parent post inline, because a bare comment body off a search index is unreadable without it: ext.post_title, ext.subreddit, ext.subreddit_subscribers, ext.post_score, ext.post_comment_count, ext.post_author, ext.post_published_at, ext.post_flair, ext.post_url and ext.content_language. Reddit's search operators work in query, which is where most of the power is: author:username returns that account's indexed comments, subreddit:name terms scopes the sweep to one community, and quoted phrases tighten a loose match. comment.parent_id is null on this lane and that is honest rather than missing — the upstream does not say whether a hit is a top-level comment or a deep reply, and this API does not guess. Up to 25 hits per page; paginate with cursor. A query that matches nothing still returns a full page of loosely-related comments rather than an empty list, which is Reddit's own search behaviour on both of this API's Reddit upstreams, so judge relevance on the rows rather than on the count. When the main source is unavailable, the first page is answered by a backup that reads the same comment index with the same fields, parent-post block included, and carries no next cursor. If that backup fails too, a third source answers the first page with the same hits but without the parent-post block, so ext.post_title, ext.post_url, ext.subreddit_subscribers, ext.post_score, ext.post_comment_count, ext.post_author, ext.post_published_at, ext.post_flair, ext.content_language and author.avatar_url are null on that page; ext.subreddit is still filled. A later page has no second source and returns an error to retry.
Request
- Base URL: https://www.socialcrawl.dev/v1
- URL: https://www.socialcrawl.dev/v1/reddit/search/comments
- Auth: API key in header x-api-key
Query parameters
Search phrase. Reddit's operators work here: author:username for one account's comments, subreddit:name terms to scope to a community, and quotes for an exact phrase.
Sort order for the comment hits.
Cursor to get more results. Get 'cursor' from the previous response.
Optional brand. data.switch_receipts lists comments where the author says they personally left that brand, with the verbatim text, the reason, where they went, and a link. There is no percentage. A comment that is not a switch, or that is not confident, is left out. No extra credits.
Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off the page, and the page that reaches one ends the walk: next_cursor is not returned and pagination.stopped_at is since. Sending it sets the newest-first sort shown in this endpoint's sort parameter (any other sort value is a free 400). The page still costs what a page costs, so you pay for the pages you walk and no more. A row with no date is kept. published_after, start_date, from_date, publish_time (yesterday, this-week, this-month, last-3-months, last-6-months) and max_age_days are accepted and applied as since.
Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. published_before, end_date and to_date are accepted and applied as until.
Headers
Send no-cache to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the no-cache directive triggers this. See the Response Schema guide for details.
Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives 409 IDEMPOTENCY_IN_PROGRESS with a Retry-After of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: credits_used becomes 0, idempotent_replay becomes true, and credits_remaining is refreshed to the current balance. A known current balance appears in both the body and X-Credits-Remaining header; no balance row resolves to 0. On a transient lookup failure, body credits_remaining is null and X-Credits-Remaining is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use Accept: application/json when sending this header. The unsupported key-plus-SSE combination is rejected before billing.
Response
Successful response
Example response
{
"success": true,
"platform": "reddit",
"endpoint": "/v1/reddit/search/comments",
"credits_used": 1,
"credits_remaining": 4999,
"request_id": "req-abc123",
"idempotent_replay": true,
"meta": {
"hint": {
"code": "search_multi",
"message": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged.",
"method": "GET",
"path": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube"
}
},
"pagination": {
"next_cursor": "sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0",
"has_more": true,
"page_size": 30,
"stopped_at": "known_id"
}
}Changes
No recorded changes to this operation across all 1 revision of this API.