OverviewPlatformsAPI Reference
Mentions

List mentions

Lists your keywords' mentions with filters and paging. Each mention pairs one post with one keyword. Latest match first by default, or sort=priority to rank the last 30 days by attention score. For the next page, send nextCursor and keep the filters and sort. alertId applies an alert's filter, giving what that alert would send. anyOf adds OR groups as URL-encoded JSON, at least one of which must match along with every other filter.

GET
/v1/mentions

Authorization

bearerAuth
AuthorizationBearer <token>

An API key from POST /v1/api-keys. Keys start with ref_.

In: header

Query Parameters

keywordId?string

Only this keyword's matches.

platform?string

Only this platform's posts.

Value in

  • "bluesky"
  • "hackernews"
  • "github"
  • "stackoverflow"
  • "devto"
  • "reddit"
  • "x"
  • "youtube"
  • "news"
  • "linkedin"
  • "tiktok"
  • "instagram"
  • "appstore"
  • "googleplay"
  • "trustpilot"
  • "googlemaps"
status?string

Keeps mentions with this status only. Leave it out for all statuses.

Value in

  • "open"
  • "ignored"
  • "done"
relevant?boolean

true keeps mentions the classifier scored relevant. false keeps the others, including unscored ones.

sentiment?string

Keeps mentions with this sentiment only.

Value in

  • "positive"
  • "neutral"
  • "negative"
intent?string

Returns only mentions with this tag. One of bug_report, buy_intent, churn_intent, comparison, complaint, event, feedback, hiring, industry_insight, launch, praise, pricing, promotional, question and testimonial.

automated?boolean

true keeps mentions that look machine-made, such as bot accounts, scheduled or template posts and AI-written text. false keeps the others, including mentions scored before this flag existed. Leave it out for all.

personId?string

Keeps mentions by this person (an id from /v1/people), including merged accounts. Turns on includeMuted.

Length1 <= length
includeMuted?boolean

true also returns mentions by muted people, which are hidden by default.

assigneeId?string

Member user id. Returns only mentions assigned to them.

Length1 <= length
snoozed?boolean

true shows only snoozed mentions, which are otherwise hidden until they wake.

excludeAuthors?array<>|

Leaves out these authors, given as display names, handles or profile links. Repeat the parameter or send one value with commas.

Itemsitems <= 200
minRelevance?|

Keeps mentions with this relevance score or higher. Unscored mentions are left out.

Range0 <= value <= 100
minConfidence?|

Minimum classifier confidence, 0 to 1. Mentions with no confidence are dropped.

Range0 <= value <= 1
minFollowers?|

Sends only posts by authors with this many followers or more. Unknown counts are left out.

Range0 <= value
maxFollowers?|

Keeps posts by authors with this many followers or fewer. Unknown counts are left out.

Range0 <= value
isReply?boolean

true keeps replies and comments, meaning posts that answer another post. false keeps posts that are not replies. Leave it out for both.

alertId?string

Adds an alert rule's filter (an id from GET /v1/alerts) to the other filters. You get the mentions the rule would send, useful for a preview or an export in feed form. An unknown id returns 404.

Length1 <= length
viewId?string

Adds a saved view's filter (an id from GET /v1/views) to the other filters, with every condition joined by AND. You get exactly what the view shows. An unknown id returns 404.

Length1 <= length
keywordKinds?array<>

Keeps matches of keywords of these kinds only (brand, competitor, topic). Repeat the parameter or separate values with commas.

Itemsitems <= 3
tags?array<>|

Keeps authors your workspace gave one of these tags, matched exactly and by case. Repeat the parameter or separate values with commas.

Itemsitems <= 20
linkHosts?array<>|

Keeps posts that link to one of these hosts or its subdomains, so slack.com also matches api.slack.com. Repeat the parameter or separate values with commas.

Itemsitems <= 20
platforms?array<>

Keeps posts from these platforms only.

Itemsitems <= 20
notPlatforms?array<>

Platforms to exclude.

Itemsitems <= 20
keywordIds?array<>|

Keeps matches of these keywords only.

Itemsitems <= 50
groupIds?array<>|

Keeps matches of keywords in these groups only (grp_...). Repeat the parameter or separate values with commas.

Itemsitems <= 50
notGroupIds?array<>|

Hides matches from keywords that belong to these groups.

Itemsitems <= 50
notKeywordIds?array<>|

Keyword ids to exclude.

Itemsitems <= 50
sentiments?array<>

Keeps mentions with these sentiments only.

Itemsitems <= 3
notSentiments?array<>

Leaves out these sentiments. Mentions not scored yet are kept.

Itemsitems <= 3
intents?array<>|

Keeps mentions tagged with one of these intents or topics.

Itemsitems <= 20
notIntents?array<>|

Intent or topic tags to exclude.

Itemsitems <= 20
notLinkHosts?array<>|

Leaves out posts that link to these hosts or their subdomains.

Itemsitems <= 20
notTags?array<>|

Leaves out authors your workspace gave one of these tags.

Itemsitems <= 20
languages?array<>

Sends only posts in these languages, as ISO 639-1 codes such as en, es or de. Posts with an unknown language are left out.

Itemsitems <= 20
notLanguages?array<>

Leaves out posts in these languages. Posts with an unknown language are kept.

Itemsitems <= 20
ratings?array<>

Keeps reviews with one of these star ratings, from 1 to 5. Use ratings=1,2 for the unhappy ones. Posts that are not reviews are left out.

Itemsitems <= 5
notRatings?array<>

Star ratings (1 to 5) to hide, such as notRatings=5. Other posts are unaffected.

Itemsitems <= 5
minLikes?|

Keeps posts with this many likes (upvotes, reactions) or more, counted when the post was collected. Posts without a like count are left out.

Range0 <= value
minReposts?|

Keeps posts with this many reposts (shares, retweets) or more, counted when the post was collected. Posts without a repost count are left out.

Range0 <= value
minReplies?|

Keeps posts with this many replies (comments) or more, counted when the post was collected. Posts without a reply count are left out.

Range0 <= value
minQuotes?|

Keeps posts with this many quotes or more, counted when the post was collected. Posts without a quote count are left out.

Range0 <= value
minViews?|

Keeps posts with this many views (plays) or more, counted when the post was collected. Posts without a view count are left out.

Range0 <= value
minBookmarks?|

Keeps posts with this many bookmarks (saves) or more, counted when the post was collected. Posts without a bookmark count are left out.

Range0 <= value
anyOf?string

Groups of conditions joined by OR, as URL-encoded JSON. For example [{"platforms":["github"],"intents":["bug_report"]},{"sentiments":["negative"]}] means "bug reports on GitHub, or anything negative". A group uses the fields of a view filter, where a list matches any value, a not list matches none, and all conditions are joined by AND. A mention passes when one group matches, and the other filters here still apply. Send 1 to 10 groups, none empty and none nested.

q?string

Searches post text and author names.

since?string

Keeps posts published at this time or later, as ISO 8601 or epoch ms.

Formatdate-time
until?string

Keeps posts published at this time or earlier, as ISO 8601 or epoch ms.

Formatdate-time
sort?string

newest orders by match time, latest first. priority orders by attention score, highest first, and only covers the past 30 days of matches. Older ones are still available with newest. A cursor only works with the sort it came from.

Default"newest"

Value in

  • "newest"
  • "priority"
cursor?string

Pass the previous page's nextCursor, with the same filters and sort.

limit?integer

How many to return, from 1 to 100.

Range1 <= value <= 100
Default25

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/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        }      },      "post": {        "platform": "bluesky",        "url": "string",        "text": "string",        "title": "string",        "imageUrl": "string",        "links": [          "string"        ],        "publishedAt": "string",        "engagement": {          "likes": 0,          "reposts": 0,          "replies": 0,          "quotes": 0,          "views": 0,          "bookmarks": 0        },        "replyTo": {          "author": "string",          "url": "string",          "text": "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": 0,        "sentiment": "positive",        "intents": [          "string"        ],        "automated": true,        "language": "string",        "confidence": 0,        "uncertain": true,        "note": "string",        "failed": true,        "feedback": {          "relevant": true,          "sentiment": "positive",          "at": "string",          "original": {            "relevance": 0,            "sentiment": "positive"          }        }      },      "triage": {        "assignee": {          "id": "string",          "name": "string",          "email": "string"        },        "snoozedUntil": "string",        "note": "string"      },      "createdAt": "string"    }  ],  "nextCursor": "string"}
Was this page helpful?

Get a mention

Fetches one mention by id, with the same fields the list returns. An id from another workspace gets a 404.

Update a mention

The only way to change a mention. Set status to ignored or done when it is handled, or back to open. You can also assign it to a member, snooze it out of the feed, add a note for your team, or correct the classifier. `relevant` true or false is your judgment, which sets relevance to 100 or 0 for every list, filter, digest and report. `sentiment` replaces the label. Null removes your correction and brings back the classifier's value. Fields you leave out stay as they are. Delivery and billing are never affected.