Update a saved query
Change any field of a saved query, including its query, schedule and status.
Headers
Get your API keyAPI key (`sfk_...`)
The saved query's id.
min 1 chars
Request body
Endpoint-specific response payload.
The current version's query, as written.
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
The current version, in Social Fetch syntax.
The current version's id.
any of: twitter, reddit, youtube, tiktok, linkedin, instagram, threads, hackernews (comma-separated)
A platform a search runs on: `twitter` (X), `reddit`, `youtube`, `tiktok`, `linkedin`, `instagram` (searched by hashtag, so only posts that use the hashtag are found), `threads` (searched by plain words, one short page a search, so it can miss posts) or `hackernews` (stories and comments). More platforms follow.
one of: twitter, reddit, youtube, tiktok, linkedin, instagram, threads, hackernews
Credits its runs charged this calendar month (UTC).
`active` runs on its schedule; `paused` doesn't; `capped` has spent its monthly credit cap and runs again next month, or when the cap is raised; `broken` stopped after its runs kept failing (see `statusReason`).
one of: active, paused, capped, broken
When it runs next, ISO 8601; null while it isn't active.
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.
Alert when it has found at least this many posts in the window.
≥ 1 · ≤ 1000000
The trailing hour or day the posts are counted over, by when they were found. The query must run at least that often: an `hour` window needs `cadenceMinutes` of 60 or less, a `day` window 1440 or less.
one of: hour, day
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.
one of: daily, weekly, null
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.
any of: jobs, giveaways, crypto-spam (comma-separated)
`jobs`: job ads and job seekers' posts; `giveaways`: giveaway and contest entry posts; `crypto-spam`: crypto promotion and money scams.
one of: jobs, giveaways, crypto-spam
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.
Judge each new match: is it about what the query 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 matches given them, on top of each run's maxCreditsPerRun but within monthlyCreditCap when one is set. A match keeps its insights: it's never judged or charged again. Matches not about it are still kept and returned; filter with `relevance`. With insights, alerts and spikes count only matches that aren't `unrelated`. Not available for zero-retention workspaces. Null or absent for off.
What the topic is about, in a few words: the name and what it is, so posts using the word another way can be told apart. For example "Notion, the note-taking app" or "Jaguar, the car brand".
min 2 chars · max 200 chars
Up to 3 yes/no questions of your own, asked of every post, such as "Does the post mention sizing or fit?". Each post's answers come back in `insights.answers`, in this order.
min 5 chars · max 200 chars
Searches each run makes on a platform instead of those planned from the query, by platform (`platformSearches` on `POST /v1/query/search`). Null for none: every platform searched as planned.
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
Matches stored for it.
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/saved-queries/abc123" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}' \
-X PATCHResponses
The updated saved query.