Search with a Boolean query
Search X, Reddit, YouTube, TikTok, LinkedIn, Instagram, Threads and Hacker News live with one Boolean query: each platform is searched in its own syntax,…
Headers
Get your API keyAPI key (`sfk_...`)
A key you choose for this search, such as a UUID. A retry with the same key and body returns the first response without charging again, for 24 hours.
pattern: ^[\x21-\x7e]{1,255}$
Request body
Endpoint-specific response payload.
The query searched, in Social Fetch's syntax.
What the query matched, across platforms. A post found twice is listed once; a repost or near-copy of another post is listed too, naming it in `duplicateOf`.
`platform:id`, unique across platforms, such as `twitter:123`.
A platform a search runs on: `twitter` (X), `reddit`, `youtube`, `tiktok`, `linkedin`, `instagram` (searched by hashtag, so only posts that use the hashtag are found), `threads` (searched by plain words, one short page a search, so it can miss posts) or `hackernews` (stories and comments). More platforms follow.
one of: twitter, reddit, youtube, tiktok, linkedin, instagram, threads, hackernews
The post's id on its platform.
The post's link.
A separate title (a Reddit post's); null when the platform has none.
Each text field, the main one first. Fields are matched one at a time, so a phrase never runs from one into the next.
The field's name, such as `text` or `body`.
The main text, for display.
The fields the query was checked against.
When it was posted, ISO 8601 in UTC.
True when the platform gave the time only roughly ("3 days ago"), so a date window can be off.
Without the @.
The subreddit, channel or group it was posted in.
Lower case, such as `en` or `es-mx`.
True when the language was detected from the text, because the platform didn't give one.
Every type the post is (a reply can also quote); null when the platform doesn't say.
Where it sits in a conversation, by the platform's own ids.
How many people it could reach, and what that's based on.
one of: views, followers, community-members
Without #.
Accounts mentioned, without @.
Links in the post, beyond its own.
Which of our operations found it, such as `twitter.search.list`.
`unknown` when the match depends on something the platform didn't return (see `unevaluableFields`).
one of: match, unknown
The query's terms found in it.
The fields its match depends on that couldn't be checked.
The query's categories it falls in.
Categories that depend on something the platform didn't return.
The post this one repeats, and why; null for a story's first or only post. Nothing is left out: group a post under the one it names to show each story once. Worked out over one search's posts: in a search's response the named post is in the same list. A saved query's matches keep what the run that first found them worked out, so the named post may be on another page, outside a filter, itself a repeat of an earlier post, or past its retention.
The `key` of the post it repeats, the earliest the search found. Follow it: it may not be in this list or page.
`repost`: it reposts that post (or the same post as it); `near-duplicate`: its text is all but the same, such as a syndicated or copied post, on any platform.
one of: repost, near-duplicate
The feeling the post expresses, when sentiment was asked for and the post got one.
one of: positive, neutral, negative
`estimate`: worked out automatically from the post's text, so it can be wrong; `manual`: set by a person.
one of: estimate, manual
How the post was judged, when insights were asked for and the post got them.
`about`: the post is about the topic; `passing`: the topic is named but the post is mainly about something else; `unrelated`: another meaning of the word, a tag on an unrelated post, or spam.
one of: about, passing, unrelated
What the post does about the topic, when it's relevant and clear: a complaint (or a problem the author had), a question, praise, buying (wants to buy or just bought), promotion (an ad, sponsored or affiliate post, or the brand's own marketing) or news. Only for posts about the topic; null otherwise.
one of: complaint, question, praise, buying, promotion, news, null
The topic's team should probably reply: the author reports a problem or asks something they could answer.
The post could hurt the topic's reputation if it spread: allegations, safety or security problems, outages, scandal, boycott calls, or a serious failure.
Your own questions, in the order asked, each answered yes or no.
The probabilities behind `relevance`, `needsReply` and `risk`, from 0 to 1, if you want your own bar. `unrelated` is at least 0.7 when relevance is unrelated; a reply needs 0.7 and a risk 0.6.
≥ 0 · ≤ 1
≥ 0 · ≤ 1
≥ 0 · ≤ 1
`estimate`: judged automatically from the post's text, so it can be wrong; `manual`: a person set its relevance.
one of: estimate, manual
How many matches each requested `noise` preset left out, each post once (zero when it left out none). Empty when none were requested.
≥ 0
≥ 0
≥ 0
A platform a search runs on: `twitter` (X), `reddit`, `youtube`, `tiktok`, `linkedin`, `instagram` (searched by hashtag, so only posts that use the hashtag are found), `threads` (searched by plain words, one short page a search, so it can miss posts) or `hackernews` (stories and comments). More platforms follow.
one of: twitter, reddit, youtube, tiktok, linkedin, instagram, threads, hackernews
How far it got: `exhausted`, every search ran to its last page; `capped`, the platform's own limit on pages stopped it; `budget`, `maxCredits` did; `deadline`, the search ran out of time (what finished is returned); `unsearchable`, nothing in the query can be searched there; `failed`, every call failed.
one of: exhausted, capped, budget, deadline, unsearchable, failed
`full`: every part of the query was searched; `partial`: some can't be (see notes); `none`: nothing could.
one of: full, partial, none
What wasn't covered, and why.
What was searched, in the platform's own syntax.
Posts read.
≥ 0
Posts the query matched, not counting those `filtered` left out.
≥ 0
Posts the query matched that the request's `noise` presets left out.
≥ 0
≥ 0
Error codes of calls that failed, with how many.
Fields the query uses that this platform doesn't return.
Plain-language cautions, most important first.
Metadata describing the request and billing outcome.
Unique request identifier for tracing this API call.
min 1 chars
Credits charged for this request.
≥ 0
Public API version that served the response.
one of: v1
Code example
curl "https://api.socialfetch.dev/v1/query/search" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"(\"social fetch\" OR socialfetch) AND (api OR scraping) -hiring","platforms":["twitter","reddit"],"since":"2026-11-01T00:00:00Z","maxCredits":40,"noise":["jobs","giveaways"]}' \
-X POSTResponses
What the query matched, and how far the search got on each platform. A search that ran out of time returns what finished, with status 200. A retry with the same Idempotency-Key and body returns this response again, with `Idempotent-Replayed: true`, and charges nothing.