Saved queries

Get a saved query's numbers

A saved query's numbers over its stored matches: posts and stories per UTC day and platform, each platform's posts, and the accounts and sites heard from…

GET/v1/saved-queries/{id}/stats
0credits
x-api-keystringheader

API key (`sfk_...`)

Parameters
3
idstringrequiredpath

The saved query's id.

min 1 chars

daysintegeroptionalquery

UTC days to count, today (the day of `now`) included, from 1 to 90. Default 30.

≥ 1 · ≤ 90

nowstringoptionalquery

The window's last day is this time's UTC day, ISO 8601. Default: now. Send the same value to read the same window again.

Response fields
55

Endpoint-specific response payload.

datasavedQueryId
string

The window: whole UTC days, oldest first.

datawindowdays
integer

UTC days in the window.

datawindowfrom
string

The first day's midnight, UTC, ISO 8601 (included).

datawindowto
string

The midnight after the last day, UTC, ISO 8601 (not included).

Posts and stories first found in the window, on every platform, dated or not. `posts` is the sum of `platforms`' posts.

datatotalsposts
integer

Posts, each repost and near-copy included.

datatotalsstories
integer

Stories: a post and its reposts and near-copies (`duplicateOf`) count once, even when the post they repeat isn't counted here (posted before the window, say). A story on several days or platforms counts once on each.

Every day in the window, oldest first, with zeros for a day without posts. A post is on the day it was posted; a post the platform gave no time for is on no day.

datadaily[]day
string

`YYYY-MM-DD`, UTC.

datadaily[]posts
integer

Posts, each repost and near-copy included.

datadaily[]stories
integer

Stories: a post and its reposts and near-copies (`duplicateOf`) count once, even when the post they repeat isn't counted here (posted before the window, say). A story on several days or platforms counts once on each.

The day's posts by platform; platforms with none are left out.

datadaily[]platforms[]platform
string

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

datadaily[]platforms[]posts
integer

Posts, each repost and near-copy included.

datadaily[]platforms[]stories
integer

Stories: a post and its reposts and near-copies (`duplicateOf`) count once, even when the post they repeat isn't counted here (posted before the window, say). A story on several days or platforms counts once on each.

Each platform's posts first found in the window, dated or not, most first.

dataplatforms[]platform
string

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

dataplatforms[]posts
integer

Posts, each repost and near-copy included.

dataplatforms[]stories
integer

Stories: a post and its reposts and near-copies (`duplicateOf`) count once, even when the post they repeat isn't counted here (posted before the window, say). A story on several days or platforms counts once on each.

Posts first found in the window by sentiment: a person's, where one was set, else the estimate.

datasentimentpositive
integer
datasentimentneutral
integer
datasentimentnegative
integer
datasentimentnone
integer

Posts with no sentiment: found while it was off, left out when a run's credits didn't cover them, or where it couldn't be worked out.

Posts first found in the window, by their insights; zeros when insights are off.

datainsightsjudged
integer

Posts given insights.

datainsightsunrelated
integer

Posts not about the query (a person's relevance, where one was set, else the estimate).

datainsightsneedsReply
integer
datainsightsrisk
integer
datainsightskindscomplaint
integer
datainsightskindsquestion
integer
datainsightskindspraise
integer
datainsightskindsbuying
integer
datainsightskindspromotion
integer
datainsightskindsnews
integer

Each of the query's own questions, with the posts answered yes.

datainsightsanswers[]question
string
datainsightsanswers[]yes
integer

Up to 10 accounts with the most posts in the window (by when posted, or found when undated), most first; ties by handle.

datatopAuthors[]platform
string

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

datatopAuthors[]handle
string

Without the @.

datatopAuthors[]name
stringnullable
datatopAuthors[]posts
integer

Posts, each repost and near-copy included.

datatopAuthors[]stories
integer

Stories: a post and its reposts and near-copies (`duplicateOf`) count once, even when the post they repeat isn't counted here (posted before the window, say). A story on several days or platforms counts once on each.

Up to 10 sites the posts in the window link to most (a post's `links`, beyond its own link), most first; ties by domain. Only http and https links to a named host count (not an IP address). A post linking to a site twice counts once. A shortened link counts as its shortener's site.

datatopSites[]domain
string

A linked site: the link's host, lower case, without `www.`, a port or a trailing dot. An international name is as the link wrote it, so its own letters and its `xn--` form count apart.

datatopSites[]posts
integer

Posts, each repost and near-copy included.

datatopSites[]stories
integer

Stories: a post and its reposts and near-copies (`duplicateOf`) count once, even when the post they repeat isn't counted here (posted before the window, say). A story on several days or platforms counts once on each.

Metadata describing the request and billing outcome.

metarequestId
string

Unique request identifier for tracing this API call.

min 1 chars

metacreditsCharged
integer

Credits charged for this request.

≥ 0

metaversion
string

Public API version that served the response.

one of: v1

Code example

curl "https://api.socialfetch.dev/v1/saved-queries/abc123/stats" \
  -H "x-api-key: YOUR_API_KEY"

Responses

The saved query's numbers over the window.