Write a Boolean query from a description

Describe what to monitor in plain words, get a Boolean query written by AI and checked before anything runs, refine it, and check your own edits

This recipe turns a plain description of what you want to monitor into a Boolean query in Social Fetch's syntax. AI writes the query; Social Fetch then reads it, explains it in plain words, plans how each platform would search it and runs it over example posts you give it, all before anything is searched. You review it, refine it in plain words or edit it, and use it once it finds what you meant.

What you'll need

An API key. The Quickstart shows how to create one.
Optionally, a few posts the query should find and a few it should leave out.

No code? The free Boolean Query Translator does the same in the browser: choose Describe it.

What it costs

Both routes in this recipe are free: POST /v1/query/suggest and POST /v1/query/validate charge 0 credits and search nothing. Writing a query is limited to 10 requests a minute and 300 a day per workspace, and checking one to 60 a minute.

Step 1: Describe what to monitor

Send what you want in brief, in any language. Add languages when the posts must be in particular languages, platforms to plan for only some, and examples with posts it should and shouldn't find.

const response = await fetch("https://api.socialfetch.dev/v1/query/suggest", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "x-api-key": process.env.SOCIALFETCH_API_KEY!,
  },
  body: JSON.stringify({
    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,
  }),
});
const { data } = await response.json();

Step 2: Read what came back

{
  "status": "suggested",
  "query": "(\"Lumora Foods\" OR Lumora OR #LumoraFoods) AND (recall* OR lawsuit* OR demanda* OR \"food poisoning\" OR intoxicación) AND NOT (hiring OR vacante) AND (lang:en OR lang:es)",
  "explanation": "Posts that ((mention “Lumora Foods” or “Lumora”) or use the hashtag #LumoraFoods), (mention a word starting with “recall”, a word starting with “lawsuit”, a word starting with “demanda”, “food poisoning” or “intoxicación”), (don't mention “hiring” and don't mention “vacante”) and (are in English (en) or are in Spanish (es)).",
  "note": "Added Spanish words for lawsuits and food poisoning, and left out job ads.",
  "examples": {
    "shouldMatch": [{ "outcome": "match", "agrees": true, "matchedTerms": ["\"Lumora Foods\"", "Lumora", "recall*", "lang:en"], "unevaluableFields": [] }],
    "shouldNotMatch": [{ "outcome": "no-match", "agrees": true, "matchedTerms": [], "unevaluableFields": [] }]
  },
  "estimatedCredits": 18,
  "warnings": [],
  "aiGenerated": true
}

Field	What it tells you
`query`	The query AI wrote. Nothing has searched with it.
`explanation`	What the query finds, written from the query itself, never by the AI, so it always says what the query does. Read it before you use the query.
`note`	A short note from the AI on what it added or assumed. Written by AI.
`examples`	How the query reads each example post, in the order you sent them. `unknown` means it depends on something the text doesn't show, such as who wrote it.
`platforms`, `estimatedCredits`	How each platform would search it, what it can't, and the most a search would cost.
`warnings`	What to check: example posts it gets wrong, names from your description it left out, languages you asked for that it doesn't limit to, platforms that can't search it.
`aiGenerated`	Always `true`. Show the query as written by AI wherever it appears.

Step 3: Refine it in plain words

To change the query, send it back as previousQuery with what to change in brief. The writer is asked to change only that and keep the rest as it was; compare the new query with the old before you use it.

body: JSON.stringify({
  brief: "also leave out posts about recipes",
  previousQuery: data.query,
  examples: { /* the same example posts */ },
}),

Step 4: Check your own edits

After you edit a query by hand, check it with POST /v1/query/validate. It returns the same explanation, plan and estimate, or where the query can't be read.

From an AI agent

Connected through MCP, the same thing is the query_suggest_post tool. Show the user the query, its explanation and its warnings, and let them accept or change it before searching with it.

When no query is written

Response	Means	Do
`200` with `status: "refused"`, `refusal.reason: "not_a_brief"`	The description names no posts to monitor	Say what the posts should be about: a brand, people, topics, places or words
`200` with `refusal.reason: "no_valid_query"`	No query that reads correctly could be written for it	Reword it, or write the query yourself and check it with validate
`200` with `refusal.reason: "unusable_answer"`	The answer couldn't be used	Reword the description
`429`	More than 10 requests a minute, or 300 a day	Retry after `Retry-After` seconds
`503`	Writing a query is unavailable right now	Retry after `Retry-After` seconds

What's sent and kept

Your description, example posts and any previousQuery are sent to an AI model to write the query, after email addresses, phone numbers, card numbers and keys are removed. For a zero-retention workspace they only go to model endpoints that keep no prompts. Social Fetch logs how long they were, never what they said.

Write a Boolean query from a description

On this page