Write a query from a description
Write a Boolean query from a plain-language description of what to monitor, optionally with example posts it should and shouldn't find, or refine an existing…
Headers
Get your API keyAPI key (`sfk_...`)
Request body
Endpoint-specific response payload.
Whether a query was suggested, or why not in `refusal`.
one of: suggested, refused
Why no query was suggested; null when one was.
`not_a_brief`: the description names no posts to monitor. `no_valid_query`: no query that reads correctly could be written for it. `unusable_answer`: the answer couldn't be used.
one of: not_a_brief, no_valid_query, unusable_answer
What to do instead, in plain language.
The suggested query, as written. Review it before searching with it.
The query with every operator explicit. It always parses back to the same query.
What the query finds, in plain language. Written from the query itself, so it always says what the query does.
Searches suggested for a platform where what's planned from the query would search badly (Instagram's hashtags, say), by platform, to send as `platformSearches`. Absent when the plan needs none. Written by AI.
Searches to run on this platform instead of those planned from the query, in its own syntax (Instagram: hashtags, with or without `#`). Posts found are still checked against the whole query.
min 1 chars · max 200 chars
Searches to run on this platform instead of those planned from the query, in its own syntax (Instagram: hashtags, with or without `#`). Posts found are still checked against the whole query.
min 1 chars · max 200 chars
Searches to run on this platform instead of those planned from the query, in its own syntax (Instagram: hashtags, with or without `#`). Posts found are still checked against the whole query.
min 1 chars · max 200 chars
Searches to run on this platform instead of those planned from the query, in its own syntax (Instagram: hashtags, with or without `#`). Posts found are still checked against the whole query.
min 1 chars · max 200 chars
Searches to run on this platform instead of those planned from the query, in its own syntax (Instagram: hashtags, with or without `#`). Posts found are still checked against the whole query.
min 1 chars · max 200 chars
Searches to run on this platform instead of those planned from the query, in its own syntax (Instagram: hashtags, with or without `#`). Posts found are still checked against the whole query.
min 1 chars · max 200 chars
Searches to run on this platform instead of those planned from the query, in its own syntax (Instagram: hashtags, with or without `#`). Posts found are still checked against the whole query.
min 1 chars · max 200 chars
Searches to run on this platform instead of those planned from the query, in its own syntax (Instagram: hashtags, with or without `#`). Posts found are still checked against the whole query.
min 1 chars · max 200 chars
A short note on the choices made, such as names or exclusions added. Written by AI.
How the query reads each example post, in the order sent.
Whether the query finds the post. `unknown`: it depends on something the text alone doesn't show, such as who wrote it.
one of: match, no-match, unknown
Whether the outcome is the one the post was given for. `unknown` never agrees.
The words, phrases and filters that matched.
What the query needed that the text doesn't show.
Whether the query finds the post. `unknown`: it depends on something the text alone doesn't show, such as who wrote it.
one of: match, no-match, unknown
Whether the outcome is the one the post was given for. `unknown` never agrees.
The words, phrases and filters that matched.
What the query needed that the text doesn't show.
The plan on each platform.
A platform a query can search.
one of: twitter, reddit, youtube, tiktok, linkedin, threads, instagram, hackernews, facebook
`full`: every part of the query can be searched; `partial`: some can't (see notes); `none`: nothing can.
one of: full, partial, none
What won't be covered, and why.
What would be searched, in the platform's own syntax.
At most what this platform would charge: its share of `maxCredits`, or less when its searches need fewer.
≥ 0
True when `searchTerms` are the searches chosen in `platformSearches`, not those planned from the query. Absent otherwise.
At most what a search with this query would charge.
≥ 0
Plain-language cautions, most important first.
Always true: the query was written by AI. Nothing runs until you search with it.
one of: true
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/suggest" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"brief":"Complaints about Lumora Foods: recalls, lawsuits and food poisoning, in English and Spanish. Not job ads.","examples":{"shouldMatch":["Lumora Foods is recalling its peanut butter after salmonella was found"],"shouldNotMatch":["Lumora Foods is hiring drivers in Leeds"]},"languages":["en","es"],"platforms":["twitter","reddit"],"maxCredits":30}' \
-X POSTResponses
A query written by AI and checked: its explanation, plan, estimate and how it reads your example posts. Or why none was written (`status: refused`).
Validate
Check a Boolean query before searching: read it (or import it from Talkwalker, Brandwatch, Meltwater, Onclusive or X, or detect which), explain it in English…
Search
Search X, Reddit, YouTube, TikTok, LinkedIn, Instagram, Threads and Hacker News live with one Boolean query: each platform is searched in its own syntax,…