List a saved query's matches
List the posts a saved query matched, newest first.
Headers
Get your API keyAPI key (`sfk_...`)
The saved query's id.
min 1 chars
Only matches first seen at or after this time.
Only matches first seen before this time.
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
Only matches with this sentiment (a person's, where one was set, else the estimate).
one of: positive, neutral, negative
Only matches with this relevance (a person's, where one was set, else the estimate); `relevant` is anything but `unrelated`. Matches without insights count as relevant.
one of: relevant, about, passing, unrelated
Only matches insights flagged as needing a reply, or as a risk.
one of: needs_reply, risk
Only matches insights judged to be this kind of post.
one of: complaint, question, praise, buying, promotion, news
Only posts by this author: their handle as the post gives it (`author.handle`), without the `@`. Pair with `platform` when the same handle could be on several.
min 1 chars · max 200 chars
Only posts whose title or text contains this, ignoring case.
min 1 chars · max 200 chars
`posted` (default): the newest posts first, by when they were posted (or found, when the platform gave no time). `found`: the most recently found first, for keeping a copy in step.
one of: posted, found
Matches a page, up to 100. Default 50.
≥ 1 · ≤ 100
The `nextCursor` of the previous page, with the same `sort`.
min 1 chars
Endpoint-specific response payload.
The saved query's matches, newest first.
A post the query matched.
`platform:id`, unique across platforms, such as `twitter:123`.
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
The post's id on its platform.
The post's link.
A separate title (a Reddit post's); null when the platform has none.
Each text field, the main one first. Fields are matched one at a time, so a phrase never runs from one into the next.
The field's name, such as `text` or `body`.
The main text, for display.
The fields the query was checked against.
When it was posted, ISO 8601 in UTC.
True when the platform gave the time only roughly ("3 days ago"), so a date window can be off.
Without the @.
The subreddit, channel or group it was posted in.
Lower case, such as `en` or `es-mx`.
True when the language was detected from the text, because the platform didn't give one.
Every type the post is (a reply can also quote); null when the platform doesn't say.
Where it sits in a conversation, by the platform's own ids.
How many people it could reach, and what that's based on.
one of: views, followers, community-members
Without #.
Accounts mentioned, without @.
Links in the post, beyond its own.
Which of our operations found it, such as `twitter.search.list`.
`unknown` when the match depends on something the platform didn't return (see `unevaluableFields`).
one of: match, unknown
The query's terms found in it.
The fields its match depends on that couldn't be checked.
The query's categories it falls in.
Categories that depend on something the platform didn't return.
The post this one repeats, and why; null for a story's first or only post. Nothing is left out: group a post under the one it names to show each story once. Worked out over one search's posts: in a search's response the named post is in the same list. A saved query's matches keep what the run that first found them worked out, so the named post may be on another page, outside a filter, itself a repeat of an earlier post, or past its retention.
The `key` of the post it repeats, the earliest the search found. Follow it: it may not be in this list or page.
`repost`: it reposts that post (or the same post as it); `near-duplicate`: its text is all but the same, such as a syndicated or copied post, on any platform.
one of: repost, near-duplicate
The feeling the post expresses, when sentiment was asked for and the post got one.
one of: positive, neutral, negative
`estimate`: worked out automatically from the post's text, so it can be wrong; `manual`: set by a person.
one of: estimate, manual
How the post was judged, when insights were asked for and the post got them.
`about`: the post is about the topic; `passing`: the topic is named but the post is mainly about something else; `unrelated`: another meaning of the word, a tag on an unrelated post, or spam.
one of: about, passing, unrelated
What the post does about the topic, when it's relevant and clear: a complaint (or a problem the author had), a question, praise, buying (wants to buy or just bought), promotion (an ad, sponsored or affiliate post, or the brand's own marketing) or news. Only for posts about the topic; null otherwise.
one of: complaint, question, praise, buying, promotion, news, null
The topic's team should probably reply: the author reports a problem or asks something they could answer.
The post could hurt the topic's reputation if it spread: allegations, safety or security problems, outages, scandal, boycott calls, or a serious failure.
Your own questions, in the order asked, each answered yes or no.
The probabilities behind `relevance`, `needsReply` and `risk`, from 0 to 1, if you want your own bar. `unrelated` is at least 0.7 when relevance is unrelated; a reply needs 0.7 and a risk 0.6.
≥ 0 · ≤ 1
≥ 0 · ≤ 1
≥ 0 · ≤ 1
`estimate`: judged automatically from the post's text, so it can be wrong; `manual`: a person set its relevance.
one of: estimate, manual
The version of the query that first found it.
The run that first found it.
Pagination state: pass `page.nextCursor` as `cursor` for the next page.
Whether another page is available.
Cursor to pass in the next request when more pages exist; null on the last page.
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/matches" \
-H "x-api-key: YOUR_API_KEY"Responses
The saved query's matches, newest first.