Run a saved query now
Run a saved query now, outside its schedule. The run is one search and charges up to the query's maxCreditsPerRun, as POST /v1/query/search does; its matches…
Headers
Get your API keyAPI key (`sfk_...`)
The saved query's id.
min 1 chars
Endpoint-specific response payload.
one of: schedule, manual
`succeeded`: every platform searched as far as the plan went; `partial`: some stopped short (time, credits, a failure), and what finished was kept; `failed`: nothing could be searched.
one of: running, succeeded, partial, failed
How far the run's search got on each platform.
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
How far it got: `exhausted`, every search ran to its last page; `capped`, the platform's own limit on pages stopped it; `budget`, `maxCredits` did; `deadline`, the search ran out of time (what finished is returned); `unsearchable`, nothing in the query can be searched there; `failed`, every call failed.
one of: exhausted, capped, budget, deadline, unsearchable, failed
`full`: every part of the query was searched; `partial`: some can't be (see notes); `none`: nothing could.
one of: full, partial, none
What wasn't covered, and why.
What was searched, in the platform's own syntax.
Posts read.
≥ 0
Posts the query matched, not counting those `filtered` left out.
≥ 0
Posts the query matched that the request's `noise` presets left out.
≥ 0
≥ 0
Error codes of calls that failed, with how many.
Fields the query uses that this platform doesn't return.
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/run" \
-H "x-api-key: YOUR_API_KEY" \
-X POSTResponses
The run started. It finishes in about a minute; see the query's runs and matches.