OverviewAPI Reference
Mentions

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.

GET
/v1/mentions

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"
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 (buy_intent, question, complaint, praise, comparison).

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.

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.

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
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
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
tags?|null

Only authors your workspace tagged with any of these (exact, case-sensitive). 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
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 intents.

Itemsitems <= 10
notIntents?|null

Never mentions carrying these intents.

Itemsitems <= 10
notLinkHosts?|null

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

Itemsitems <= 20
notTags?|null

Never authors your workspace tagged with any of these.

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
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

application/json

application/json

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"
      },
      "post": {
        "platform": "bluesky",
        "url": "string",
        "text": "string",
        "links": [
          "string"
        ],
        "publishedAt": "string",
        "replyTo": {
          "author": "string",
          "url": "string",
          "text": "string"
        }
      },
      "author": {
        "id": "string",
        "name": "string",
        "handle": "string",
        "url": "string",
        "avatarUrl": "string",
        "followers": 0,
        "tags": [
          "string"
        ]
      },
      "classification": {
        "relevance": 100,
        "sentiment": "positive",
        "intents": [
          "string"
        ],
        "automated": true,
        "language": "string",
        "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"
      },
      "createdAt": "string"
    }
  ],
  "nextCursor": "string"
}
{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "requestId": "string",
    "retryAfterSeconds": 0
  }
}
{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "requestId": "string",
    "retryAfterSeconds": 0
  }
}

Get a mention GET

One mention by id, as it appears in the list: the post, its author with reach and your tags, the classification, the priority score and the triage fields. Ids belong to your organization; any other id is a 404.

Update a mention PATCH

The one write on a mention. Set status to ignored or done to handle it (open puts it back), assign it to a workspace member, snooze it out of the feed, leave an internal note, or correct the classifier: `relevant` true or false is your verdict (relevance becomes 100 or 0, and every list, filter, digest and report follows it), `sentiment` replaces the label; null withdraws a verdict and restores the classifier's value. Omitted fields are untouched. Delivery and billing never change.