# Mentio

> Social listening for developer platforms, API-first. Mentio watches Bluesky, Hacker News, Reddit, X, GitHub, Stack Overflow, DEV, YouTube, LinkedIn and news for the keywords you track, classifies every mention for relevance, sentiment and intent, and delivers it through a REST API, a TypeScript SDK, a CLI, an MCP server and webhooks.

The API is described by an OpenAPI document at https://api.mentio.dev/v1/openapi.json. Every page below is also available as Markdown at the linked address; the whole site is in one file at https://docs.mentio.dev/llms-full.txt.

## When to use Mentio

- The user asks who is talking about their product, brand, a competitor or a topic on developer platforms, or wants that watched continuously with alerts to Slack, email, webhooks or Telegram.
- The user needs mentions classified (relevance 0 to 100, sentiment, intent: buy intent, question, complaint, praise, comparison) or triaged (open, ignored, done, assigned, snoozed), the people behind them (reach, profile, tags, segments), or share of voice against competitors.
- The user names Mentio, its REST API, SDKs, CLI, MCP server or OpenClaw skill.
- Not for private or paid content: Mentio reads public posts on the platforms above only, and it is not a posting or engagement tool.

## How to call it

- REST: https://api.mentio.dev/v1 with `Authorization: Bearer mk_live_...`. A person creates the key at https://app.mentio.dev/api-keys; there is no OAuth server and no unattended signup. Details: https://mentio.dev/auth.md.
- MCP (streamable HTTP): https://mcp.mentio.dev/mcp, server card at https://mcp.mentio.dev/.well-known/mcp/server-card.json. `initialize`, `tools/list` and the resources need no key; `tools/call` does.
- Documentation MCP (read-only, no key): https://docs.mentio.dev/api/mcp, card https://docs.mentio.dev/.well-known/mcp.json. Tools: search_docs, read_page, list_pages.
- SDKs and CLI: npm `@mentio-dev/sdk`, PyPI `mentio`, `npx @mentio-dev/cli`. Skill for agents: https://mentio.dev/.well-known/agent-skills/mentio/SKILL.md.
- Versioning: the API lives under `/v1`; additive changes never break a client, and a breaking change would ship as a new path with Deprecation and Sunset headers on the old one (https://docs.mentio.dev/conventions.mdx).
- Changelog: https://docs.mentio.dev/changelog (Markdown at https://docs.mentio.dev/changelog.mdx, RSS at https://docs.mentio.dev/changelog/rss.xml), newest first, one entry per user-facing change.

## Guides

- [Overview](https://docs.mentio.dev/index.mdx): What Mentio is, how a mention travels from a platform to your inbox, and the five ways to build on it.
- [Alerts and channels](https://docs.mentio.dev/alerts.mdx): Rules decide what you hear about and when. Channels are where it lands.
- [Slack integration](https://docs.mentio.dev/alerts/slack.mdx): Connect a workspace and get relevant mentions posted to a channel.
- [Telegram integration](https://docs.mentio.dev/alerts/telegram.mdx): Get mention alerts and daily digests in a Telegram chat or group.
- [Authentication](https://docs.mentio.dev/authentication.mdx): Bearer API keys, scopes, and key management.
- [Billing](https://docs.mentio.dev/billing.mdx): The prepaid balance, what a keyword-day and a mention cost, and the wallet and ledger endpoints.
- [CLI](https://docs.mentio.dev/cli.mdx): Every endpoint as a mentio command, plus a live feed and MCP setup, for scripts and terminals.
- [Account commands](https://docs.mentio.dev/cli/account.mdx): Who you are, keys, the company profile, usage, the wallet, the team, the stored login, MCP setup and a health check.
- [Alerts, channels and attention commands](https://docs.mentio.dev/cli/alerts.mdx): Rules that decide what you hear about, the channels it lands in, and what needs attention.
- [Analytics commands](https://docs.mentio.dev/cli/analytics.mdx): The four reports over one window: summary, series, breakdown, share of voice.
- [Keywords, groups and feeds commands](https://docs.mentio.dev/cli/keywords.mdx): Track, tune, mute and remove the terms Mentio watches, and group them by customer or campaign.
- [Mentions and views commands](https://docs.mentio.dev/cli/mentions.mdx): Search, read, triage and export mentions, follow the feed live, and save a filter as a view.
- [People and segments commands](https://docs.mentio.dev/cli/people.mdx): The authors behind the mentions, your annotations on them, and saved segments.
- [Conventions](https://docs.mentio.dev/conventions.mdx): The rules every endpoint follows, so one resource teaches you all of them.
- [Errors](https://docs.mentio.dev/errors.mdx): The error envelope and every stable error code.
- [Needs attention](https://docs.mentio.dev/guides/attention.mdx): Spikes, negative spikes, noisy keywords and failing channels, found for you once an hour and sent where you choose.
- [Comments](https://docs.mentio.dev/guides/comments.mdx): Read the conversation under your mentions. Comments are items like posts; the ones that name your keyword are mentions too.
- [Keyword groups](https://docs.mentio.dev/guides/groups.mdx): Group keywords by customer, campaign or product, track the same term in more than one group, and read what each group cost.
- [Keyword health](https://docs.mentio.dev/guides/keyword-health.mdx): Find the keywords that cost more than they bring, see what their noise is made of, and apply the fix with one PATCH.
- [Choosing keywords](https://docs.mentio.dev/guides/keywords.mdx): How a keyword matches a post, how to pick terms that find what you want, and what you pay for.
- [Views](https://docs.mentio.dev/guides/views.mdx): Saved filters over your mentions. Switch between them on the Mentions page, read one through the API with viewId, export one as CSV.
- [How it works](https://docs.mentio.dev/how-it-works.mdx): The ingestion pipeline, per-platform freshness, and the mention lifecycle.
- [OpenClaw](https://docs.mentio.dev/integrations/openclaw.mdx): Install the Mentio skill from ClawHub so OpenClaw tracks keywords, searches and triages mentions, sets up alerts and reads analytics from natural language.
- [MCP server](https://docs.mentio.dev/mcp.mdx): Connect Claude Code, Cursor, Codex, Gemini, VS Code and any MCP client to your mention feed.
- [Tools](https://docs.mentio.dev/mcp/tools.mdx): Every tool the MCP server exposes, by area.
- [Migrate from Octolens](https://docs.mentio.dev/migrate/octolens.mdx): Point your Octolens code, CLI and integrations at Mentio by changing the base URL and the key, copy your keywords, feeds and filters over with one script, then cut over.
- [Platforms](https://docs.mentio.dev/platforms.mdx): Where Mentio looks, how often, and how far back a new keyword reads, platform by platform.
- [App Store](https://docs.mentio.dev/platforms/appstore.mdx): Reviews of the iPhone and iPad apps a keyword names, with their stars, title and app version.
- [Bluesky](https://docs.mentio.dev/platforms/bluesky.mdx): Every Bluesky post naming your keyword, in real time from the network's firehose.
- [DEV](https://docs.mentio.dev/platforms/devto.mdx): New DEV articles whose title, description or tags name your keyword.
- [GitHub](https://docs.mentio.dev/platforms/github.mdx): GitHub issues, pull requests and repositories naming your keyword, with the author's public profile.
- [Google reviews](https://docs.mentio.dev/platforms/googlemaps.mdx): Google reviews of a place on Google Maps, with the stars, the owner's reply and the reviewer.
- [Google Play](https://docs.mentio.dev/platforms/googleplay.mdx): Reviews of the Android apps a keyword names, with their stars, app version and the developer's reply.
- [Hacker News](https://docs.mentio.dev/platforms/hackernews.mdx): Every Hacker News story and comment naming your keyword.
- [Instagram](https://docs.mentio.dev/platforms/instagram.mdx): Public Instagram posts and reels naming your keyword in their caption or hashtags.
- [LinkedIn](https://docs.mentio.dev/platforms/linkedin.mdx): Public LinkedIn posts naming your keyword, by people and company pages.
- [News](https://docs.mentio.dev/platforms/news.mdx): News articles from around the web whose headline or named people and organisations include your keyword.
- [Reddit](https://docs.mentio.dev/platforms/reddit.mdx): Reddit posts naming your keyword, in any subreddit.
- [How reviews work](https://docs.mentio.dev/platforms/reviews.mdx): Collect App Store, Google Play, Trustpilot and Google reviews of your product or a competitor's as mentions of a keyword, with the stars and the owner's reply.
- [RSS feeds](https://docs.mentio.dev/platforms/rss.mdx): Forums, communities and blogs no platform search reaches, read through their RSS or Atom feed.
- [Stack Overflow](https://docs.mentio.dev/platforms/stackoverflow.mdx): Stack Overflow questions and answers naming your keyword.
- [TikTok](https://docs.mentio.dev/platforms/tiktok.mdx): New TikTok videos whose caption, hashtags or speech name your keyword, with views, likes and the creator's reach.
- [Trustpilot](https://docs.mentio.dev/platforms/trustpilot.mdx): Reviews of a company's Trustpilot page, with the stars, the verified badge and the company's reply.
- [X](https://docs.mentio.dev/platforms/x.mdx): Posts and replies naming your keyword, with the full engagement counts and the author's profile.
- [YouTube](https://docs.mentio.dev/platforms/youtube.mdx): YouTube videos whose title or description names your keyword.
- [Quickstart](https://docs.mentio.dev/quickstart.mdx): A keyword, the company profile, a search and a triage in five calls.
- [Rate limits](https://docs.mentio.dev/rate-limits.mdx): 600 requests a minute per workspace, the headers that tell you where you stand, and what to do with a 429.
- [SDKs](https://docs.mentio.dev/sdks.mdx): Typed clients for the Mentio API, generated from its OpenAPI document. TypeScript and Python are published; any other language is a generator run away.
- [Python](https://docs.mentio.dev/sdks/python.mdx): The mentio package, one call per endpoint, sync and async.
- [TypeScript](https://docs.mentio.dev/sdks/typescript.mdx): The @mentio-dev/sdk package, one typed function per endpoint.
- [Webhooks](https://docs.mentio.dev/webhooks.mdx): How deliveries work: the flow, retries, idempotency, signature verification, and the events you can receive.
- [Account events](https://docs.mentio.dev/webhooks/account-events.mdx): Webhooks for keyword and wallet state changes and attention items, with no mention behind them.
- [Digest events](https://docs.mentio.dev/webhooks/digest-events.mdx): What an hourly, daily or weekly rule sends once a period.
- [Mention events](https://docs.mentio.dev/webhooks/mention-events.mdx): What an instant rule sends for every matching mention.

## API reference

- [Introduction](https://docs.mentio.dev/api.mdx): Every Mentio endpoint, generated from the live OpenAPI spec.
- [Create an alert](https://docs.mentio.dev/api/alerts/create-alert.mdx): A rule (what to watch, the filter) times channels. mode instant sends each matching mention as it happens; hourly sends one digest every UTC hour (five minutes past) for the previous full hour, nothing when it had no mention over the rule's floor, to Slack, Telegram and webhook channels only (no schedule); daily sends one digest at schedule.hour in schedule.timezone; weekly sends one a week on schedule.weekday (0 Sunday to 6 Saturday). filter.anyOf adds OR: groups of conditions in the vocabulary of the mentions list, at least one of which must hold on top of the rest of the filter.
- [Create a channel](https://docs.mentio.dev/api/alerts/create-channel.mdx)
- [Delete an alert](https://docs.mentio.dev/api/alerts/delete-alert.mdx)
- [Delete a channel](https://docs.mentio.dev/api/alerts/delete-channel.mdx)
- [Get an alert](https://docs.mentio.dev/api/alerts/get-alert.mdx)
- [Get a channel](https://docs.mentio.dev/api/alerts/get-channel.mdx)
- [List alerts](https://docs.mentio.dev/api/alerts/list-alerts.mdx)
- [List deliveries to a channel](https://docs.mentio.dev/api/alerts/list-channel-deliveries.mdx)
- [List channels](https://docs.mentio.dev/api/alerts/list-channels.mdx)
- [Mute authors on an alert](https://docs.mentio.dev/api/alerts/mute-alert-authors.mdx): Add authors to the alert's muted list without touching the rest of its filter. Links are read the way the dashboard reads them: a post link mutes its author, twitter.com becomes x.com, a Hacker News profile keeps its id. Authors already muted are skipped, so a retry is safe. An entry that names no person (a subreddit, a story) rejects the request with that entry named.
- [Rotate a webhook secret](https://docs.mentio.dev/api/alerts/rotate-webhook-secret.mdx)
- [Send a digest now](https://docs.mentio.dev/api/alerts/run-alert-digest.mdx)
- [Send a test through an alert's channels](https://docs.mentio.dev/api/alerts/test-alert.mdx)
- [Send a test to a channel](https://docs.mentio.dev/api/alerts/test-channel.mdx)
- [Unmute authors on an alert](https://docs.mentio.dev/api/alerts/unmute-alert-authors.mdx): Remove authors from the alert's muted list without touching the rest of its filter. Name each one by the stored entry or by any link to that profile or its posts. Authors that are not muted are ignored, so a retry is safe.
- [Update an alert](https://docs.mentio.dev/api/alerts/update-alert.mdx)
- [Update a channel](https://docs.mentio.dev/api/alerts/update-channel.mdx)
- [Mentions grouped by one dimension](https://docs.mentio.dev/api/analytics/get-analytics-breakdown.mdx): One table of matched, relevant and sentiment counts grouped by `by`: platform, keyword, sentiment, intent, status, hour (weekday and hour of day) or person. The window is `range` (7d, 30d, 90d, 365d, ending today) or `from` and `to`, cut into days in `timezone` (UTC by default); `keywordIds` and `platforms` narrow it; `compare=true` adds the period of the same length right before it. Time axis is the publish date.
- [Mentions over time](https://docs.mentio.dev/api/analytics/get-analytics-series.mdx): Matched, relevant and sentiment counts per day or week across the window, as one total series or split per platform or per keyword with `by`. The window is `range` (7d, 30d, 90d, 365d, ending today) or `from` and `to`, cut into days in `timezone` (UTC by default); `keywordIds` and `platforms` narrow it; `compare=true` adds the period of the same length right before it. Time axis is the publish date.
- [Headline counts for a window](https://docs.mentio.dev/api/analytics/get-analytics-summary.mdx): Matched and relevant mentions, distinct posts and people, sentiment, buying intent and questions, estimated reach, and where the matches stand in triage. The window is `range` (7d, 30d, 90d, 365d, ending today) or `from` and `to`, cut into days in `timezone` (UTC by default); `keywordIds` and `platforms` narrow it; `compare=true` adds the period of the same length right before it. Time axis is the publish date.
- [Reviews: stars over a window, per review page](https://docs.mentio.dev/api/analytics/get-reviews-report.mdx): The reviews a keyword collects (App Store, Google Play, Trustpilot, Google Maps): count, average stars, distribution, replies and open 1-2 star reviews, for the workspace and per review page with a series of average stars per `bucket`, plus the tags the unhappy reviews carry. A review matched by two keywords counts once. The window is `range` (7d, 30d, 90d, 365d, ending today) or `from` and `to`, cut into days in `timezone` (UTC by default); `keywordIds` and `platforms` narrow it; `compare=true` adds the period of the same length right before it. Time axis is the publish date.
- [Brand against competitors](https://docs.mentio.dev/api/analytics/get-share-of-voice.mdx): Every keyword matched in the window with its counts and its share of brand plus competitor matches; topic keywords are counted but stay out of the split. The window is `range` (7d, 30d, 90d, 365d, ending today) or `from` and `to`, cut into days in `timezone` (UTC by default); `keywordIds` and `platforms` narrow it; `compare=true` adds the period of the same length right before it. Time axis is the publish date.
- [Create an API key](https://docs.mentio.dev/api/api-keys/create-api-key.mdx): Mint a key for this workspace. The key itself is returned once; only its hash is stored. `expiresAt` makes it stop working at an instant (a key for a contractor or a one-off script); it stays listed until revoked.
- [List API keys](https://docs.mentio.dev/api/api-keys/list-api-keys.mdx)
- [Revoke an API key](https://docs.mentio.dev/api/api-keys/revoke-api-key.mdx): Takes effect at once on the API and within a few minutes on cached verifications.
- [Dismiss an attention item](https://docs.mentio.dev/api/attention/dismiss-attention.mdx): Put an item away. It leaves the open list and does not come back while its condition lasts; once the condition clears, a new episode may open a new item. Idempotent.
- [List attention items](https://docs.mentio.dev/api/attention/list-attention.mdx): What needs a person, newest first: a keyword whose mentions spiked in the last hour (mention.spike), whose negative share of the last 24 hours jumped (sentiment.negative_spike), that turned noisy (keyword.noisy), or a channel whose last sends all failed (channel.failing). Detected once an hour; an item opens when its condition starts and resolves on its own when the condition is gone. Open items by default; `status=all` reads the history. Each opening is also an account event of the same name, which webhook, Slack, email and Telegram channels can subscribe to.
- [Introspect the credential](https://docs.mentio.dev/api/auth/whoami.mdx): The workspace this credential acts on, how the request authenticated (an API key, an OAuth access token from an MCP sign-in, or the dashboard session), whether it may write, and for a key its id and expiry. Run it first: a read key answers 403 read_only_key on every write, and a wrong workspace is the classic scripting mistake.
- [Create a top-up checkout](https://docs.mentio.dev/api/billing/create-top-up.mdx): Returns a hosted checkout URL with `amountCents` prefilled (editable there, $20 to $5,000). The balance is credited when the payment lands, within a minute, and tracking the wallet had paused resumes at once. Nothing is charged by this call itself. `successUrl` must be on an origin this deployment trusts; omit it for the dashboard's billing page.
- [Get a receipt link](https://docs.mentio.dev/api/billing/get-invoice-url.mdx): A short-lived link to the receipt PDF of one paid order (an id from the receipts list).
- [Get the wallet](https://docs.mentio.dev/api/billing/get-wallet.mdx): The prepaid balance in full: ledger, pending mention charges and the effective balance the stop rule reads, the daily burn and the days it buys, how many keywords run and how many the wallet paused, what a day costs and what a resume needs, the welcome credit, the newest top-up, the top-up bounds and the auto-recharge settings. `GET /v1/usage` is the short form.
- [List receipts](https://docs.mentio.dev/api/billing/list-invoices.mdx): The orders behind the top-ups, newest first, as the merchant of record (Polar) holds them: this workspace's share of the billing customer's newest 100 orders. Empty before the first top-up.
- [List ledger entries](https://docs.mentio.dev/api/billing/list-ledger.mdx): Every movement of the balance, newest first: the welcome credit, top-ups, refunds, the daily keyword-day and mention debits, adjustments. A debit row carries the UTC day it settled and the cumulative units behind it. Cursor paged.
- [Get the company profile](https://docs.mentio.dev/api/company/get-company.mdx): What the classifier knows about you: name, description, use cases, your own accounts, and the composed context it reads.
- [Update the company profile](https://docs.mentio.dev/api/company/update-company.mdx): Changing profile fields recomposes the classifier context; setting `context` directly overrides it until the next profile edit. Relevance scores for new mentions follow at once.
- [Connect a feed](https://docs.mentio.dev/api/feeds/create-feed.mdx): Connect an RSS or Atom feed: a feed's address, or a page's (a forum, a community, a blog), in which case the feed the page advertises is used, else a usual address such as /feed or /rss. Every keyword of the workspace with readsWorkspaceFeeds (the default) reads these feeds: an item holding its term is one of its mentions, with its matching rules, billed like any mention. Each feed is read every hour; reading it is free. At most 500 a workspace. A new feed brings each reading keyword the newest 10 items of the last 30 days that hold its term, never as instant alerts. A feed the workspace reads already comes back with 200 (connecting is idempotent). A members-only forum answers `feed_login_required`: send it again with `auth` (a cookie or a header), stored encrypted and read for this workspace alone.
- [Disconnect a feed](https://docs.mentio.dev/api/feeds/delete-feed.mdx): The workspace stops reading the feed. Its mentions stay; a keyword naming the same feed in its own `feeds` keeps reading it.
- [Get a feed](https://docs.mentio.dev/api/feeds/get-feed.mdx)
- [Connect many feeds](https://docs.mentio.dev/api/feeds/import-feeds.mdx): Connect up to 100 feeds in one call, each { url } or { url, auth } for a members-only one, checked on its own and reported added, already or failed, in the order sent: one that fails never stops the others. A failure carries the error code POST /v1/feeds would answer for that address (feed_login_required: send it again with auth). Every keyword of the workspace with readsWorkspaceFeeds (the default) reads these feeds: an item holding its term is one of its mentions, with its matching rules, billed like any mention. Each feed is read every hour; reading it is free. At most 500 a workspace. The first 8 added bring each reading keyword the newest 10 matching items of the last 30 days; the rest start from now.
- [List feeds](https://docs.mentio.dev/api/feeds/list-feeds.mdx): The RSS and Atom feeds the workspace reads (forums, communities, blogs), newest connection first, each with how its hourly poll goes. Every keyword of the workspace with readsWorkspaceFeeds (the default) reads these feeds: an item holding its term is one of its mentions, with its matching rules, billed like any mention. Each feed is read every hour; reading it is free. At most 500 a workspace.
- [Update a feed](https://docs.mentio.dev/api/feeds/update-feed.mdx): Rename a feed (title, null clears it), or set its sign-in for a members-only forum (auth: a cookie copied from your browser, or one header such as Discourse's Api-Key). A sign-in is checked by reading the feed with it, stored encrypted, sent to the feed's own site alone and never shown again; the feed is then read for this workspace alone. auth: null removes it.
- [Get the workspace filters](https://docs.mentio.dev/api/filters/get-filters.mdx): The noise rules applied to every keyword before a mention is stored: excluded terms and authors, excluded GitHub repositories, and the subreddits Reddit posts may (or may not) come from. A post they reject is never classified, delivered or billed. Keyword-level rules live on each keyword (`matching`); both apply.
- [Update the workspace filters](https://docs.mentio.dev/api/filters/update-filters.mdx): Replace any of the lists; an omitted list is untouched and an empty one clears it. Entries are stored in canonical form (terms lowercased, authors as profile links or bare names, repositories as owner/name, subreddits without r/). Takes effect on new mentions within a minute; stored mentions are untouched.
- [Create a group](https://docs.mentio.dev/api/groups/create-group.mdx): Create a keyword group. `name` is unique per workspace; `externalId` (optional, unique too) is your own id for it, a customer id say, so you can find it again without storing ours; `context` (optional) is the group's own company description, which the classifier reads in place of the whole workspace profile for the group's keywords. Then pass the group id as `groupId` when creating a keyword.
- [Delete a group and its keywords](https://docs.mentio.dev/api/groups/delete-group.mdx): Deletes the group and EVERY keyword in it, each the way DELETE /v1/keywords/{id} does (its mentions go with it, alert rules that named it are adjusted; charges already made stay on the usage record). Read the group first: `stats.keywords` says how many go. The default group cannot be deleted: move or delete its keywords instead.
- [Get a group](https://docs.mentio.dev/api/groups/get-group.mdx)
- [List groups](https://docs.mentio.dev/api/groups/list-groups.mdx): The keyword groups of the workspace, the default group first, then oldest first. A group is how keywords are grouped (a customer, a campaign, a product): a term may be tracked once per group, every keyword belongs to one, and GET /v1/usage/breakdown?by=group says what each group cost. Pass `externalId` to find the group carrying your own id.
- [Update a group](https://docs.mentio.dev/api/groups/update-group.mdx): Rename a group, change your id for it (`externalId`, null clears) or its company description (`context`, null clears: the workspace profile applies again; new mentions are judged with it at once, old ones are not rescored). The default group can be renamed like any other but takes no description: it is the workspace itself and reads the company profile.
- [Track a keyword](https://docs.mentio.dev/api/keywords/create-keyword.mdx): Start tracking a word or phrase. Matching, classification and delivery begin on the next poll. A funded workspace tracks up to 500 keywords; each costs $5 per month, deducted daily from the balance. `matching` narrows what the term matches (required and excluded terms, excluded authors, case, subreddits, GitHub repository events) before a mention is stored, so a rejected post is never billed; `context` is a sentence the classifier reads for this keyword only. `cap` puts a monthly ceiling on its matched mentions: at the cap it stops matching until the first of the next month (UTC) or until the cap is raised, while its daily keyword charge continues.
- [Delete a keyword](https://docs.mentio.dev/api/keywords/delete-keyword.mdx): Removes the keyword and its matches. Posts also matched by another keyword stay.
- [Duplicate a keyword](https://docs.mentio.dev/api/keywords/duplicate-keyword.mdx): A new keyword with this one's settings and a new `term` (or the same term in another group): its kind, platforms, context, every matching rule, its monthly mention cap and its comments setting. Review apps and feeds are copied only when listed in `include`. It is a new keyword: $5 per month, and the newest posts of the last 30 days come in at once, as with any new keyword.
- [Get a keyword](https://docs.mentio.dev/api/keywords/get-keyword.mdx)
- [Get a keyword's health](https://docs.mentio.dev/api/keywords/get-keyword-health.mdx): Whether the keyword earns what it costs over a trailing window (`range`, default 30d): a status (healthy, noisy, quiet, capped, paused, new) with the reasons in plain words, its numbers by platform and week, what it cost, the words and authors its noise is made of, and suggestions. Each suggestion carries a `patch` to send to PATCH /v1/keywords/{id} as is, and the effect it would have had, measured by running the matcher's own rules over the window's posts. `ai=true` adds a context rewritten by a language model (cached a day, at most 20 model calls an hour per workspace). Read only and never billed; the report is cached for 5 minutes, and a change to the keyword starts a fresh one. At most 30 reads a minute per workspace.
- [List keywords](https://docs.mentio.dev/api/keywords/list-keywords.mdx): The keywords of the workspace with their match stats and poll health. Without parameters: every keyword, newest first. `q` searches the term and the context; `kind`, `status` and `platform` narrow the list; `sort` orders it; `limit` and `offset` page it. `total` counts the keywords that matched before paging.
- [Update a keyword](https://docs.mentio.dev/api/keywords/update-keyword.mdx): Rename it (`term`: the new term is tracked from now on, with no look-back; the mentions the old term found stay), mute or unmute it, reclassify it (`kind`), change the platforms it is tracked on, its classifier `context`, its `matching` rules (each rule field optional; an empty list clears one), or its monthly mention `cap` (null removes it; a cap above this month's count resumes a capped keyword at once). Rules apply to new mentions from the next poll; stored mentions are untouched.
- [Invite a member](https://docs.mentio.dev/api/members/create-invitation.mdx): Send an email invitation to join the workspace as admin or member; it expires after 48 hours. Idempotent: an address that already holds an open invitation gets it back with 200 and no second email. An address that is already a member is a 409 already_member. Team changes need a signed-in owner or admin (an OAuth token from an MCP sign-in, or the dashboard session): an API key answers 403.
- [List pending invitations](https://docs.mentio.dev/api/members/list-invitations.mdx): Invitations sent and not yet accepted, declined or expired. An accepted one appears in GET /v1/members instead.
- [List members](https://docs.mentio.dev/api/members/list-members.mdx): Everyone in the workspace, owners first. `userId` is what a mention's assigneeId and a person's ownerId take.
- [Remove a member](https://docs.mentio.dev/api/members/remove-member.mdx): The person loses the workspace within a minute (their dashboard session on the next request, an OAuth token when its short cache lapses). Their mentions, notes and outreach stay. Needs a signed-in owner or admin; only an owner removes another owner, and the last owner cannot be removed (409 last_owner).
- [Revoke an invitation](https://docs.mentio.dev/api/members/revoke-invitation.mdx): The link in the email stops working at once. Needs a signed-in owner or admin; an API key answers 403.
- [Export mentions as CSV](https://docs.mentio.dev/api/mentions/export-mentions-csv.mdx): The same mentions GET /v1/mentions would list for these filters, as CSV, newest matched first (the order they entered your feed, which can differ from the post date): id, published_at, platform, keyword, author, author_url, author_followers, relevance, sentiment, intents (pipe-separated), language, confidence, status, relevant, delivered, url, links (pipe-separated), text (first 1,000 characters), group, group_external_id, rating and app_id (app store reviews only), title and image_url (where the platform has them), duplicate_of (the mention a cross-post copies; the CSV keeps one row per mention, copies included; with includeHidden=true, the mentions a keyword hides by language or country too, it adds up to the bill), kind (post, comment or repository), parent_url (the post a comment answers), comments (comments of it delivered to you), subreddit and flair (Reddit only), country (where the author is, ISO 3166-1 alpha-2, empty when unknown) and organization (true when a company or organization posted). Capped at 10,000 rows; the X-Mentions-Truncated header says when the cap cut the list. At most 6 exports per minute per workspace; a 429 carries Retry-After.
- [Export mentions as JSON](https://docs.mentio.dev/api/mentions/export-mentions-json.mdx): The same mentions GET /v1/mentions would list for these filters, in one response, newest matched first (the order they entered your feed): every row is the full Mention object the list returns, text included. Capped at 10,000 mentions; `truncated` (and the X-Mentions-Truncated header) says when the cap cut the list. Shares the CSV export's limit: at most 6 exports per minute per workspace, either format; a 429 carries Retry-After.
- [Get a mention](https://docs.mentio.dev/api/mentions/get-mention.mdx): 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.
- [List the comments of a mention](https://docs.mentio.dev/api/mentions/list-mention-comments.mdx): The comments under a mention's post, newest first: every comment in the thread, whether or not it names your keyword. Read once, about a day after the post, for mentions scored relevant whose keyword has comments enabled (keywords.comments), on Hacker News, Bluesky, GitHub, Stack Overflow, DEV, YouTube and Reddit; empty before that and for other keywords. Each comment delivered costs $0.008 on the comments line of the bill, once per workspace. A comment that itself names one of your keywords is also a mention: `mentionId` links it. Two mentions of one post (two keywords) list the same thread.
- [List mentions](https://docs.mentio.dev/api/mentions/search-mentions.mdx): 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.
- [Update a mention](https://docs.mentio.dev/api/mentions/update-mention.mdx): 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.
- [Delete an outreach activity](https://docs.mentio.dev/api/people/delete-person-activity.mdx): Remove a contact logged by mistake. The person's owner and stage stay as they are. With `groupId`, the call works inside that keyword group: its people, and its own tags, notes, mute, merges and activities, apart from the workspace's and from every other group's.
- [Export people as CSV](https://docs.mentio.dev/api/people/export-people-csv.mdx): The same list as GET /v1/people (segmentId included) as CSV, one row per person with their contact columns: handle, followers, email, website, company, location, tags, then outreach stage, owner and last contacted. Capped at 5,000 people. `groupId` scopes the export like the list. At most 6 exports per minute per workspace; a 429 carries Retry-After.
- [Get a person](https://docs.mentio.dev/api/people/get-person.mdx): One person as your workspace sees them. An account merged into someone resolves to that person. With `groupId`, the call works inside that keyword group: its people, and its own tags, notes, mute, merges and activities, apart from the workspace's and from every other group's.
- [List people](https://docs.mentio.dev/api/people/list-people.mdx): The people behind your mentions: one row per person, with their accounts, reach, public profile, per-workspace stats, your annotations and where your outreach stands. Filter by platform, tag, follower range, mention counts, intents seen, keyword kinds mentioned or never mentioned, outreach stage, owner, automated (bot accounts, whose matched posts are mostly machine-made), or a saved segment. Offset-paginated with a total. With `groupId`, only the people who mentioned that keyword group's keywords, counted over those mentions, with that group's own annotations, merges, outreach and segments.
- [List outreach activities](https://docs.mentio.dev/api/people/list-person-activities.mdx): Every logged contact with this person across all their accounts, newest first (at most 200): who reached out, the channel, when, and a short note. Read it before reaching out so two teammates never contact the same person without knowing. With `groupId`, the call works inside that keyword group: its people, and its own tags, notes, mute, merges and activities, apart from the workspace's and from every other group's.
- [Log an outreach activity](https://docs.mentio.dev/api/people/log-person-activity.mdx): Record that a teammate reached out to this person: an email, a DM, a call. The first activity claims an unowned person for whoever reached out and moves not_contacted to contacted; an existing owner and a later stage are kept. `memberId` defaults to the signed-in member; an API key that omits it logs an unattributed activity, which claims nobody. With `groupId`, the call works inside that keyword group: its people, and its own tags, notes, mute, merges and activities, apart from the workspace's and from every other group's.
- [Merge an account into a person](https://docs.mentio.dev/api/people/merge-people.mdx): Declare that this account and another person are the same human, for your workspace only. Their mentions, tags, notes and outreach activities combine under the person named by `into`, which keeps its owner and stage unless it had none. With `groupId`, the call works inside that keyword group: its people, and its own tags, notes, mute, merges and activities, apart from the workspace's and from every other group's.
- [Undo a merge](https://docs.mentio.dev/api/people/split-person.mdx): The account becomes its own person again. With `groupId`, the call works inside that keyword group: its people, and its own tags, notes, mute, merges and activities, apart from the workspace's and from every other group's.
- [Update your annotations on a person](https://docs.mentio.dev/api/people/update-person.mdx): Tags, notes, mute, and the outreach owner (a workspace member; null clears) and stage, for your workspace only. Mute hides their posts from your feed and every channel; ingest and billing never change. With `groupId` the annotations are that keyword group's own: `muted` hides the person, and the accounts that group merged into them, from the mentions of that group's keywords only (feed, alerts and digests), and the group's tags show on those mentions next to the workspace's. A mute set without `groupId` hides them everywhere.
- [Create a segment](https://docs.mentio.dev/api/segments/create-segment.mdx): Save a named filter over your people. With `groupId` the segment belongs to that keyword group: it is listed, counted and changed only there, and its name only has to be unique in the group.
- [Delete a segment](https://docs.mentio.dev/api/segments/delete-segment.mdx): Nobody in it is affected. Pass the `groupId` the segment was saved in.
- [Get a segment](https://docs.mentio.dev/api/segments/get-segment.mdx): One segment of the scope the call names: the workspace, or the keyword group in `groupId`. A segment saved in another scope is a 404.
- [List segments](https://docs.mentio.dev/api/segments/list-segments.mdx): Your saved segments, each with the number of people in it right now (segments are evaluated on every read, never materialized), plus presets you can save as a starting point. Pass a segment id to GET /v1/people to list its members. With `groupId`, that keyword group's own segments, counted over its own people; without it, the workspace's. A segment belongs to one scope and is not visible from another.
- [Update a segment](https://docs.mentio.dev/api/segments/update-segment.mdx): Only the fields sent change. Pass the `groupId` the segment was saved in; a segment cannot move between scopes.
- [Get Health](https://docs.mentio.dev/api/system/get-health.mdx)
- [Get usage and balance](https://docs.mentio.dev/api/usage/get-usage.mdx): The prepaid balance (ledger, pending mention charges, and the effective balance the stop rule reads), the daily burn and the days it buys, the keywords the wallet runs and pauses, the matches recorded today and over 30 days, and whether tracking is stopped or the balance is low. Every matched mention bills ($0.008), relevant or not; every active keyword bills $5 a month, charged daily.
- [Get the usage breakdown](https://docs.mentio.dev/api/usage/get-usage-breakdown.mdx): What the workspace consumed and was charged over a window, grouped by one dimension per call (`by`: day, platform or keyword), in USD cents at list price, with the window's totals on every call. `range` reads a trailing window of UTC days ending today (default 30d); `month` reads one calendar month (YYYY-MM), the shape a bill or a per-customer margin is reconciled against. Keyword-days come from the daily tick and mention charges from the matches that billed, so a deleted keyword keeps its charges in the keyword rows (`keyword.removed`) while its mention counts read 0; the same numbers ride on each keyword as `stats.cost` for the running month. `totals.ledgerDebitCents` is what the wallet has debited so far for the window's days: mentions settle the morning after their day, so a window ending today lags `totals.totalCents` by the unsettled ones, and a closed month differs from it only by cumulative rounding. Rows are paged (`limit`, `offset`, `total`); a workspace may read this at most 30 times a minute through its keys and tokens together.
- [Save a view](https://docs.mentio.dev/api/views/create-view.mdx): Save a named filter over mentions. The filter takes the same fields as GET /v1/mentions (lists are any-of, `not` lists none-of, every condition ANDed), plus `anyOf`, groups of those conditions of which at least one must hold; an empty filter is every mention. Nothing is materialized: the view selects whatever matches when it is read.
- [Delete a view](https://docs.mentio.dev/api/views/delete-view.mdx): Removes the view. No mention is affected.
- [Get a view](https://docs.mentio.dev/api/views/get-view.mdx)
- [List views](https://docs.mentio.dev/api/views/list-views.mdx): The saved views of the workspace, oldest first. A view is a named filter over mentions: pass its id as `viewId` to GET /v1/mentions or the export to read exactly what it selects.
- [Update a view](https://docs.mentio.dev/api/views/update-view.mdx): Rename, describe or refilter a view. `filter` replaces the whole filter.