Create a saved query
saved_queries_createSave a Boolean social media query to run on a schedule, store new matching posts, and optionally send them to a webhook with alerts or briefings.
Instructions
Save a Boolean query to run on a schedule and keep the posts it matches. Each run searches live, charges what its searches cost (never more than maxCreditsPerRun) and stores new matches; optionally sends them to a webhook endpoint. alertThreshold optionally alerts when it finds at least that many posts in an hour or a day (the saved_query.threshold webhook event); briefing optionally adds a daily or weekly briefing, in the app and to that endpoint; noise leaves out job ads, giveaways or crypto spam; platformSearches optionally sets what each run searches on a platform instead of what's planned from the query (every post is still checked against the whole query); sentiment optionally gives each new match a sentiment estimate, a paid extra out of each run's credits; insights (what the topic is about, and up to 3 yes/no questions) optionally judges each new match's relevance, kind, need of a reply and risk, 1 credit per 10 matches judged. Runs once straight away unless runNow is false. Check the query with query_validate_post first. Refused for a workspace that keeps no request content.
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": {
"name": "<name>",
"query": "<query>",
"maxCreditsPerRun": "<maxCreditsPerRun>",
"cadenceMinutes": "<cadenceMinutes>",
"context": "<context>",
"llm_model": "<llm_model>"
},
"name": "saved_queries_create"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | A name for the query, shown in the dashboard and in alerts. | |
| noise | No | Kinds of post its runs leave out: `jobs` (job ads and job seekers' posts), `giveaways` (giveaway and contest entry posts), `crypto-spam` (crypto promotion and money scams). Checked on each post after it's found, so a run costs the same. Empty, the default, leaves everything in. | |
| query | Yes | The Boolean query. Check it for free first with POST /v1/query/validate. | |
| runNow | No | Run it once straight away rather than at its first scheduled time. Default true. | |
| 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. | |
| briefing | No | A briefing on what it found: `daily` covers the day before (UTC) and comes at 08:00 UTC; `weekly` covers Monday to Sunday and comes on Monday at 08:00 UTC. It counts the posts, the change on the period before, the stories, each platform's posts, the loudest voices and the 5 most engaged posts, is shown on the query in the Listening app, and is sent to its webhook endpoint as the `saved_query.briefing` event. Only for an active query that ran in the period without failing. Null for none, the default. | |
| insights | No | ||
| 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. Empty means every platform search covers. | |
| sentiment | No | Give each new match a sentiment estimate (positive, neutral or negative), for 1 credit per 10 matches given one, on top of each run's maxCreditsPerRun but within monthlyCreditCap when one is set. Only matches given one are charged. A match keeps its sentiment: it's never estimated or charged again. Default false. | |
| alertThreshold | No | A volume alert: when a run brings the posts it found in the trailing `window` to at least `posts`, it sends the `saved_query.threshold` webhook event, at most once a window. The first run of a query or of a new wording doesn't alert (it finds the backlog). Null for none. | |
| cadenceMinutes | Yes | Minutes between scheduled runs, from 15 to 10080 (a week). | |
| 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. | |
| maxCreditsPerRun | Yes | The most one run may charge, held while it runs as with POST /v1/query/search; what isn't used is given back. | |
| monthlyCreditCap | No | The most all its runs may charge in a calendar month (UTC). Null for no cap beyond each run's. | |
| platformSearches | No | ||
| webhookEndpointId | No | A webhook endpoint of this workspace to send new matches to (event `saved_query.matches`), spikes (event `saved_query.spike`: far more posts in 24 hours than its usual day), volume alerts (event `saved_query.threshold`) and briefings (event `saved_query.briefing`). |