List mentions
GET https://datafa.st/api/v1/mentionsSearch stored X and Reddit mentions for one website.
Required account-token permission:
analytics:read.Query parameters
startAt / endAtstring
Supply together. Inclusive YYYY-MM-DD dates or ISO timestamps with Z/offset. Defaults to the last 30 calendar days, including today.
timezonestring
IANA timezone; defaults to the website timezone. Date-only bounds include the entire local day.
qstring
Case-insensitive text search, up to 200 characters.
limitinteger
Page size, 1–1000; default 100.
offsetinteger
Rows to skip; default 0.
orderstring
desc (newest first, default) or asc.Pagination returns
limit, offset, total, and hasMore. Unknown or duplicate query parameters are rejected.websiteIdstring
Required with
dft_; inferred from df_.platformstring
x or reddit; omit for both.The
q search matches post text, author name/username, URL, and subreddit. Relevance filtering and the Starter sample match the chart and happen before search, platform filtering, sorting, and pagination.Response
Each
data item includes id, websiteId, platform, timestamp (UTC ISO), text, url, author (name, username, image), and engagement. X items also include media and isRetweet; Reddit items include subreddit. X engagement contains likes, replies, reposts, and quotes; Reddit contains score and comments.pagination.total counts accessible matches after search. meta.totalMentions counts all relevant stored mentions in the date range before the plan cap/search. meta.sampled indicates withheld results; meta.mentionLimit is 3 for limited access and null for full access. meta also returns the resolved timezone and UTC date bounds. Starter responses include meta.message explaining that Starter provides a sample and meta.upgradeUrl linking to https://datafa.st/dashboard/billing to unlock all available mentions with Growth. These fields are present even for empty or filtered Starter results; Growth responses omit them.MCP:
datafast_mentions_list accepts the same parameters.Authentication
Use
Authorization: Bearer df_... for one website, or dft_... with the required permission and website access. Notes always require websiteId in the path. Mention reads infer it from a website key; account tokens must provide the websiteId query parameter.Existing website keys and
* account tokens work automatically. For restricted account tokens, open Account settings → API, expand your token, choose Edit permissions, and enable Notes → Read / Write. Save permissions to keep the same token and MCP connection. Only the signed-in token owner can edit permissions in the dashboard; no API or MCP operation can do this.Errors
Standard errors use
{ "status": "error", "error": { "code": 400, "message": "..." } }. Expect 400 for invalid fields, dates, or IDs; 401 for invalid credentials; 403 for missing permissions or website access; 404 for a missing website/note; 409 for reusing a creation key with different input; and 429 for the normal API rate limit.