List mentions
List mentions (brand mentions your listeners matched), cursor-paginated. sort is newest (default, by datePublished descending) or fitScore (by AI fit score descending, unscored mentions last).
Cursor pagination only — mentions insert continuously, so this endpoint does not support offset/page pagination. Pass meta.nextCursor from a response as cursor on the next request. When meta.hasMore is false, there is nothing more to fetch. A cursor is only valid for the sort it was minted under; reusing it with a different value returns a validation error.
Because newest sorts by publish date, a mention backfilled or found via a delayed crawl can carry an older datePublished than mentions you've already paginated past, and will not appear in a subsequent page. sort=fitScore has a similar but more general risk: AI fit score can be overwritten by reanalysis after insert, so a mention re-scored while you're mid-pagination can occasionally be skipped or duplicated across pages. Prefer sort=newest if you need a gap-free stream.
status defaults to ready (unarchived). Note that status and AI analysis (ai.*, including fitScore) are point-in-time, not live: a mention synced before it was archived or re-scored will not reflect the change unless you re-fetch it.
platform, sentiment, fitScore, languages, includeIntents/excludeIntents, listenerIds/excludeListenerIds, and includeKeywords/excludeKeywords all take comma-separated values. dateFrom/dateTo filter on datePublished (note: independent of sort).
Read-only — this endpoint does not consume credits.
Authorization
bearerAuth Organization API key (sf_api_… from Integrations → API keys) or a partner OAuth 2.1 access token issued by SnitchFeed (authorization_code + refresh). OAuth tokens must be audience-bound to this API (resource = {apiOrigin}/v1) and carry the route scopes listed per operation.
In: header
Query Parameters
Opaque cursor from a previous response's meta.nextCursor.
1 <= value <= 10025newest (default): by datePublished, descending. fitScore: by AI fit score, descending, unscored mentions last — mutable after insert, so this sort can occasionally skip or duplicate a re-scored mention across pages; prefer newest for a gap-free stream.
"newest"Value in
- "newest"
- "fitScore"
Comma-separated platforms to include: any of reddit, twitter, bluesky, linkedin, hackernews.
Comma-separated sentiments to include: any of positive, negative, neutral.
Defaults to ready (unarchived) mentions.
Value in
- "ready"
- "archived"
Comma-separated AI fit score buckets to include: any of high, medium, low. Unset means all buckets (including unscored mentions).
Comma-separated listener ids (lis_...) to filter to (a single id works too). Ids from another organization or that don't exist are dropped; if none of the given ids resolve, the result is empty rather than unfiltered.
Comma-separated listener ids (lis_...) to exclude. Ids that don't resolve are ignored.
Comma-separated AI intent tag slugs — only mentions with at least one of these tags. One or more of buying_intent, recommendation_request, comparison, seeking_alternative, content_opportunity, pain_point, competitor_complaint, competitor_mention, feature_request, praise, hiring, brand_mention, promotional.
Comma-separated AI intent tag slugs — excludes mentions with any of these tags. Same slugs as includeIntents.
Comma-separated keywords — only mentions matched by at least one of these keywords.
Comma-separated keywords — excludes mentions matched by any of these keywords.
Comma-separated ISO 639-1 language codes to include (e.g. en,fr) — matches ai.language on the mention.
ISO 8601 instant. Only mentions published at or after this time (filters on datePublished, the same column this endpoint sorts by).
ISO 8601 instant. Only mentions published at or before this time (filters on datePublished, the same column this endpoint sorts by).
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/mentions"{ "requestId": "string", "mentions": [ { "id": "string", "listenerId": "string", "platform": "reddit", "keywords": [ "string" ], "status": "ready", "datePublished": "string", "dateFound": "string", "content": { "url": "string", "text": "string", "author": "string", "authorUrl": "string", "title": "string", "subreddit": "string", "engagement": { "score": 0, "comments": 0, "shares": 0, "retweets": 0 } }, "ai": { "sentiment": "positive", "fitScore": 0, "intentTags": [ "string" ], "summary": "string", "language": "string" }, "snitchfeedUrl": "string" } ], "meta": { "hasMore": true, "nextCursor": "string" }}Search HackerNews POST
Search HackerNews stories and comments (via Algolia's HN index). ### Query syntax `query` supports HN's native search qualifiers in addition to plain keywords: `author:USERNAME` / `by:USERNAME` (filter by author), `story:ID` (filter to one story's items), `points>N` / `points<N`, `comments>N` / `comments<N`, `"exact phrase"`, and `-word` (exclude). A query can be qualifiers-only with no keywords, e.g. `author:pg points>500`. ### Credits Each **successful** response deducts **2 credits** from your organization. Requests that fail (4xx / 5xx) are not billed. See the [credits documentation](https://snitchfeed.com/docs/api/credits) for the full rate table.
Count mentions GET
Count mentions matching the given filters, without fetching or paginating them. Accepts the same filters as `GET /mentions` (excluding `cursor`, `limit`, and `sort`, which only affect pagination order). **Read-only** — this endpoint does not consume credits.