List mentions

Mentions matched to your keywords, filtered and paginated. Default order is newest match first; sort=priority ranks the last 30 days of matches by attention score. Page with nextCursor, passing the same filters and sort. A mention is one post matched to one keyword. alertId applies an alert rule's filter on top of the others: the same mentions that rule would send. anyOf adds OR: URL-encoded JSON groups of conditions, at least one of which must hold on top of every other filter.

Authorization

AuthorizationBearer <token>

API key minted via POST /v1/api-keys (format mk_live_...)

In: header

Query Parameters

keywordId?string

Only matches of this keyword.

platform?string

Only posts from this platform.

Value in

"bluesky" | "hackernews" | "github" | "stackoverflow" | "devto" | "reddit" | "x" | "youtube" | "news" | "linkedin" | "tiktok" | "instagram" | "appstore" | "googleplay" | "trustpilot" | "googlemaps" | "rss"

status?string

Only mentions in this status. Omit for every status.

Value in"open" | "ignored" | "done"

relevant?boolean

true: only mentions the classifier scored relevant; false: only the rest (unclassified included).

sentiment?string

Only this sentiment.

Value in"positive" | "neutral" | "negative"

intent?string

Only mentions carrying this intent or topic tag (buy_intent, question, complaint, praise, comparison, churn_intent, bug_report, pricing, hiring, event, promotional, testimonial, industry_insight, launch, feedback).

automated?boolean

true: only mentions that read as machine-made (a bot account, a scheduled or templated post, AI-written text); false: only the rest, mentions judged before this existed included. Omitted: everything.

organization?boolean

true: only posts by companies, brands and organizations (a LinkedIn company page, a GitHub organization, a business account); false: only posts by people, mentions judged before this existed included. Omitted: everything.

personId?string

Only this person (an id from /v1/people), merged accounts included. Implies includeMuted.

Length1 <= length

includeMuted?boolean

true: include mentions by people you muted, hidden by default: muted for the workspace, or for the mention's own keyword group.

includeHidden?boolean

true: include mentions their keyword's display lists hide (a language or country it does not show), hidden by default.

includeDuplicates?boolean

true: list cross-posts (a mention whose duplicateOf is set) as mentions of their own. By default each is listed only in its original's duplicates.

assigneeId?string

Only mentions assigned to this workspace member (user id).

Length1 <= length

snoozed?boolean

true: only mentions currently snoozed. Otherwise snoozed mentions stay out until they wake.

excludeAuthors?|null

Hide these authors: display names, handles or profile URLs. Repeatable, or one comma-separated value.

Itemsitems <= 200

minRelevance?integer|null

Only mentions scored at least this; unclassified ones are excluded.

Range0 <= value <= 100

minConfidence?number|null

Only mentions whose classifier confidence is at least this, 0 to 1. Mentions without a confidence are excluded.

Range0 <= value <= 1

minFollowers?integer|null

Only authors with at least this many followers. Unknown reach never passes.

Range0 <= value

maxFollowers?integer|null

Only authors with at most this many followers. Unknown reach never passes.

Range0 <= value

kind?string

Only posts (post), only comments (comment) or only GitHub repository events (repository). Omitted: all.

Value in"post" | "comment" | "repository"

isReply?boolean

true: only replies and comments (posts answering another post); false: only top-level posts. Omitted: both.

alertId?string

Apply an alert rule's filter (an id from GET /v1/alerts) on top of the other filters: the same mentions the rule would send, for a feed-shaped export or a preview. Unknown ids are a 404.

Length1 <= length

viewId?string

Apply a saved view's filter (an id from GET /v1/views) on top of the other filters, every condition ANDed: exactly what the view selects. Unknown ids are a 404.

Length1 <= length

keywordKinds?array<string>

Only matches of keywords of any of these kinds: brand, competitor, topic. Repeatable, or comma-separated.

Itemsitems <= 3

tags?|null

Only authors tagged with any of these (exact, case-sensitive), in the workspace's tags or those of the mention's own keyword group. Repeatable, or comma-separated.

Itemsitems <= 20

linkHosts?|null

Only posts linking to any of these hosts, the host itself or a subdomain of it (octolens.com also matches blog.octolens.com). Repeatable, or comma-separated.

Itemsitems <= 20

platforms?array<string>

Only posts from any of these platforms.

Itemsitems <= 20

notPlatforms?array<string>

Never posts from these platforms.

Itemsitems <= 20

keywordIds?|null

Only matches of any of these keywords.

Itemsitems <= 50

groupIds?|null

Only matches of keywords in any of these groups (grp_...). Repeatable, or comma-separated.

Itemsitems <= 50

notGroupIds?|null

Never matches of keywords in these groups.

Itemsitems <= 50

notKeywordIds?|null

Never matches of these keywords.

Itemsitems <= 50

sentiments?array<string>

Only these sentiments.

Itemsitems <= 3

notSentiments?array<string>

Never these sentiments. A mention the classifier has not scored yet still passes.

Itemsitems <= 3

intents?|null

Only mentions carrying any of these intent or topic tags.

Itemsitems <= 20

notIntents?|null

Never mentions carrying these intent or topic tags.

Itemsitems <= 20

notLinkHosts?|null

Never posts linking to these hosts, the host itself or a subdomain of it.

Itemsitems <= 20

subreddits?|null

Only Reddit posts from any of these subreddits: subreddits=SaaS,startups (names without the r/, any case). Every other post fails it. Repeatable, or comma-separated.

Itemsitems <= 50

notSubreddits?|null

Never Reddit posts from these subreddits; posts from other platforms still pass.

Itemsitems <= 50

notTags?|null

Never authors tagged with any of these, in the workspace's tags or those of the mention's own keyword group.

Itemsitems <= 20

languages?array<string>

Only posts in any of these languages (ISO 639-1: en, es, de). A post whose language is unknown never passes.

Itemsitems <= 20

notLanguages?array<string>

Never posts in these languages. A post whose language is unknown still passes.

Itemsitems <= 20

countries?array<string>

Only posts whose author is in any of these countries (ISO 3166-1 alpha-2: us, in, de), as the classifier read the author's profile and the post. A post whose country is unknown never passes.

Itemsitems <= 100

notCountries?array<string>

Never posts whose author is in these countries: notCountries=in. A post whose country is unknown still passes.

Itemsitems <= 100

ratings?array<integer>

Only app store reviews with any of these star ratings (1 to 5): ratings=1,2 is the unhappy ones. Every other post fails it.

Itemsitems <= 5

notRatings?array<integer>

Never reviews with these star ratings (1 to 5): notRatings=5 hides the five star reviews. Posts that are not reviews still pass.

Itemsitems <= 5

minLikes?integer|null

Only posts with at least this many likes (upvotes, reactions), as the platform reported them when the post was found. A post without that count never passes.

Range0 <= value

minReposts?integer|null

Only posts with at least this many reposts (shares, retweets), as the platform reported them when the post was found. A post without that count never passes.

Range0 <= value

minReplies?integer|null

Only posts with at least this many replies (comments), as the platform reported them when the post was found. A post without that count never passes.

Range0 <= value

minQuotes?integer|null

Only posts with at least this many quotes, as the platform reported them when the post was found. A post without that count never passes.

Range0 <= value

minViews?integer|null

Only posts with at least this many views (plays), as the platform reported them when the post was found. A post without that count never passes.

Range0 <= value

minBookmarks?integer|null

Only posts with at least this many bookmarks (saves), as the platform reported them when the post was found. A post without that count never passes.

Range0 <= value

anyOf?string

OR across groups of conditions, as URL-encoded JSON: [{"platforms":["reddit"],"sentiments":["negative"]},{"intents":["buy_intent"]}] is "negative on Reddit, or buying intent anywhere". Each group holds the conditions of a view filter (lists any-of, not lists none-of, all ANDed); a mention passes when at least one group holds, and every other filter here still applies. 1 to 10 groups, none empty, no nesting.

q?string

Substring search in the post text or the author's name.

since?string

Only posts published at or after this instant (ISO 8601, or epoch ms).

Formatdate-time

until?string

Only posts published at or before this instant (ISO 8601, or epoch ms).

Formatdate-time

sort?string

newest: by match time, newest first. priority: by attention score, highest first; priority ranks the last 30 days of matches only, older ones stay reachable under newest. Cursors are specific to a sort.

Default"newest"

Value in"newest" | "priority"

cursor?string

nextCursor from the previous page; pass the same filters and sort.

limit?integer

Page size, 1 to 100.

Default25

Range1 <= value <= 100

Response Body

application/json

curl -X GET "https://api.mentio.dev/v1/mentions"

curl -X GET "https://api.mentio.dev/v1/mentions"

{
  "data": [
    {
      "id": "string",
      "status": "open",
      "relevant": true,
      "delivered": true,
      "priority": 0,
      "keyword": {
        "id": "string",
        "term": "string",
        "group": {
          "id": "string",
          "name": "string",
          "externalId": "string",
          "isDefault": true
        },
        "matchedAs": "phrase",
        "matchedIn": "text"
      },
      "post": {
        "platform": "bluesky",
        "kind": "post",
        "url": "string",
        "text": "string",
        "title": "string",
        "imageUrl": "string",
        "subreddit": "string",
        "flair": "string",
        "repository": {
          "name": "string",
          "event": "new",
          "stars": 0,
          "weeklyStars": 0
        },
        "links": [
          "string"
        ],
        "publishedAt": "string",
        "engagement": {
          "likes": 0,
          "reposts": 0,
          "replies": 0,
          "quotes": 0,
          "views": 0,
          "bookmarks": 0
        },
        "replyTo": {
          "author": "string",
          "url": "string",
          "text": "string"
        }
      },
      "parentMentionId": "string",
      "author": {
        "id": "string",
        "name": "string",
        "handle": "string",
        "url": "string",
        "avatarUrl": "string",
        "followers": 0,
        "tags": [
          "string"
        ]
      },
      "review": {
        "rating": 1,
        "ratingMax": 0,
        "title": "string",
        "version": "string",
        "country": "string",
        "verified": true,
        "response": "string",
        "responseAt": "string",
        "app": {
          "platform": "appstore",
          "id": "string",
          "url": "string"
        }
      },
      "classification": {
        "relevance": 100,
        "sentiment": "positive",
        "intents": [
          "string"
        ],
        "automated": true,
        "language": "string",
        "country": "string",
        "organization": true,
        "confidence": 1,
        "uncertain": true,
        "note": "string",
        "failed": true,
        "feedback": {
          "relevant": true,
          "sentiment": "positive",
          "at": "string",
          "original": {
            "relevance": 100,
            "sentiment": "positive"
          }
        }
      },
      "triage": {
        "assignee": {
          "id": "string",
          "name": "string",
          "email": "string"
        },
        "snoozedUntil": "string",
        "note": "string"
      },
      "duplicateOf": "string",
      "duplicates": [
        {
          "id": "string",
          "platform": "bluesky",
          "url": "string",
          "publishedAt": "string"
        }
      ],
      "stats": {
        "comments": 0
      },
      "createdAt": "string"
    }
  ],
  "nextCursor": "string"
}

{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "requestId": "string",
    "retryAfterSeconds": 0
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "requestId": "string",
    "retryAfterSeconds": 0
  }
}

List mentions

Authorization

Query Parameters

Response Body

200application/json

400application/json

401application/json

application/json

application/json

application/json