Search with a Boolean query
query_search_postSearch X, Reddit, YouTube, TikTok, LinkedIn, Instagram, Threads, and Hacker News live with one Boolean query; each platform uses its syntax, duplicates merge, and maxCredits caps cost.
Instructions
Search X, Reddit, YouTube, TikTok, LinkedIn, Instagram, Threads and Hacker News live with one Boolean query: each platform is searched in its own syntax, every post is checked against the whole query, and duplicates are merged. Charges what its searches cost, never more than maxCredits, and says how far it got on each platform. Check the query with query_validate_post first: it's free and estimates the cost. Returns every match at once, no cursor. Pass the same idempotencyKey to retry a search without being charged again; without one, each call is a new, charged search.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"query": "<query>",
"maxCredits": "<maxCredits>",
"context": "<context>",
"llm_model": "<llm_model>"
},
"name": "query_search_post"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| noise | No | Kinds of post to leave out of the matches, such as job ads. Checked on each post after it's found, so the search itself isn't narrowed and the credits are the same. How many each left out is in `filtered`. None by default. | |
| query | Yes | The Boolean query. Check it for free first with POST /v1/query/validate. | |
| since | No | Earliest post time, between 2000 and 2100. Overrides a date in an imported query. | |
| until | No | Latest post time, between 2000 and 2100, not before `since`. Overrides a date in an imported query. | |
| strict | No | Leave out posts whose match depends on something the platform didn't return (`outcome: unknown`). Default false. | |
| syntax | No | 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`. | |
| context | Yes | Describe the user's underlying goal in one sentence, not the tool you are calling. | |
| insights | No | Judge each post found: is it about what the topic is about, what is it (a complaint, question, praise, buying, promotion or news), does it need a reply, is it a risk, and up to 3 yes/no questions of your own. 1 credit per 10 posts given them, on top of maxCredits, as sentiment: only posts given insights are charged; if your balance or the key's monthly limit can't cover it, posts come back without them and nothing is charged, said in warnings. Every post is still returned, whatever its relevance. Not available with zero data retention. | |
| llm_model | Yes | The exact model identifier you (the assistant) are running as, taken from your system prompt or environment (for example "claude-opus-4-8" or "gpt-5.2"). Used for analytics only. If you do not know your model identifier with certainty, pass "unknown" and do not guess. | |
| platforms | No | Platforms to search. Every platform when omitted. | |
| sentiment | No | Estimate each post's sentiment (positive, neutral or negative), for 1 credit per 10 posts given one, on top of maxCredits: the searches still get all of maxCredits, and every post they find with text is given one. Only posts given one are charged. If your balance or the key's monthly limit can't cover it, the posts come back without one and nothing is charged for it, said in warnings. Default false. | |
| maxCredits | Yes | The most this search may charge, shared evenly between the platforms with something to search. Held from your balance while it runs; what isn't used is given back. | |
| idempotencyKey | No | A key you choose for this search, such as a UUID; send the same one to retry it safely: the first response comes back, charging nothing. Each call is its own search without one. | |
| conversation_id | No | Echo the conversation_id from the server's previous response. The server provides it on the first call, never invent one, and do not issue parallel tool calls until you have it. | |
| platformSearches | No | Searches to run on a platform instead of those planned from the query, by platform. A platform left out is searched as planned. Only changes what's searched: every post is still checked against the whole query. |