Validate a Boolean query
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…
Headers
Get your API keyAPI key (`sfk_...`)
Request body
Endpoint-specific response payload.
Whether the query can be read.
Why it can't be read; null when valid.
Machine-readable reason, such as `ambiguous_precedence`.
What's wrong and how to fix it.
Where the problem starts in the query (UTF-16 offset).
Where it ends (UTF-16 offset, exclusive).
The query in Social Fetch's syntax, with every operator explicit. It always parses back to the same query.
The query in plain language.
With `syntax: auto`, the syntax the query was read in and why; null otherwise. Send that syntax to search with it.
Syntax the query is written in: `native` (Social Fetch's Boolean language), or another tool's to import: `x` (X search), `onclusive`, `talkwalker`, `brandwatch` (also Cision Social Listening) or `meltwater`.
one of: native, x, onclusive, talkwalker, brandwatch, meltwater
What gave the syntax away, as written in the query, such as `NEAR/2f`; empty when nothing did.
How an imported query carried over; null for native queries.
Another tool's syntax: `x` (X search), `onclusive`, `talkwalker`, `brandwatch` (also Cision Social Listening) or `meltwater`.
one of: x, onclusive, talkwalker, brandwatch, meltwater
The worst clause's status, summarised.
one of: exact, approximate, partial
Where the clause starts in the query.
Where it ends (exclusive).
The clause as written.
How faithfully the clause carried over.
one of: exact, equivalent, approximated, unsupported
What changed, in plain language.
The clause in Social Fetch's syntax, when there is one.
A date the imported query held (X's since:).
A date the imported query held (X's until:).
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 these settings would charge.
≥ 0
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/validate" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"from:nasa OR from:esa -filter:replies","syntax":"x","platforms":["twitter","reddit"],"since":"2026-11-01T00:00:00Z","maxCredits":20}' \
-X POSTResponses
The query read, explained and planned, or why it can't be read (`valid: false`, with the error's position).
Ask
Route a natural-language social-data question to the right lookup when you do not yet know the typed tool — prefer typed tools once the operation is known.
Suggest
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…