--- title: "Social Listening API: Mentions From 17 Platforms | Mentio" description: "A social listening API: track keywords on 17 platforms, search AI-scored mentions, get signed webhooks. TypeScript and Python SDKs, CLI and MCP." canonical: https://mentio.dev/api/ markdown: https://mentio.dev/api/index.md last-updated: 2026-11-10T13:33:29.117Z --- # Social Listening API: Mentions From 17 Platforms | Mentio > A social listening API: track keywords on 17 platforms, search AI-scored mentions, get signed webhooks. TypeScript and Python SDKs, CLI and MCP. Source: https://mentio.dev/api/ For developers # Social listening API Track keywords on 17 platforms and get every mention back scored for relevance, sentiment and intent. Search it over REST, receive it on a signed webhook, or hand it to an AI agent over MCP. ``` curl "https://api.mentio.dev/v1/mentions?platform=reddit&relevant=true&limit=25" \ -H "Authorization: Bearer $MENTIO_API_KEY" ``` 17 platformsSigned webhooks600 requests a minuteTypeScript, Python, CLI, MCP [Get an API key with $5.80 free credit](https://app.mentio.dev/login?mode=signup)[API docs](https://docs.mentio.dev/quickstart) ## What is the Mentio API? A social media monitoring API you do not have to build. You tell it the terms you care about (your brand, your competitors, the problem you solve) and Mentio searches every platform for them on its side, on each platform's own schedule: Reddit every 30 minutes, X every hour, Bluesky as posts are published. Every match is scored once against a description of your company: relevance from 0 to 100, sentiment, intent and topic tags such as `buy_intent`, `question` and `complaint`, and a one-line note. Your code reads a feed that is already filtered and labeled, instead of raw search results from a dozen vendors. The API is the product: the dashboard at app.mentio.dev is one client of it, and everything it does, you can do with a key. ## What can you do with it? 76 public operations, grouped by resource. These are the ones most integrations start with. [ Mentions GET /v1/mentions Search every mention your keywords matched, filtered by platform, keyword, relevance, sentiment, intent, language, followers, links, rating, text and time range. Cursor pages, CSV export, and PATCH to triage. ](https://docs.mentio.dev/api/mentions/search-mentions)[ Keywords POST /v1/keywords Create, list, update and delete the terms you track: brand, competitor or topic, per platform, with required and excluded terms, a context sentence for the classifier and an optional mention cap per day, week or month. ](https://docs.mentio.dev/api/keywords/create-keyword)[ Alerts and webhooks POST /v1/alerts Rules with a filter that send matching mentions to Slack, Telegram, email or your own URL, instantly or as a daily digest. Webhooks are signed with HMAC-SHA256 and carry a delivery log. ](https://docs.mentio.dev/webhooks)[ Analytics GET /v1/analytics/summary A summary against the previous period, a time series, a breakdown by platform, keyword, sentiment, intent, language or person, and share of voice against your competitors. ](https://docs.mentio.dev/api/analytics/get-analytics-summary)[ People GET /v1/people The authors behind your mentions, with profiles, follower counts, tags, notes and activity, plus segments, merges of the same person across platforms, and a CSV export. ](https://docs.mentio.dev/api/people/list-people)[ Views, groups and usage GET /v1/usage/breakdown Saved filters over mentions, keyword groups per customer or campaign, and the cost of every keyword over any window, for resellers who bill their own clients. ](https://docs.mentio.dev/guides/groups) ## What does a request look like? Create a keyword, then read what it matched. A new keyword starts with up to 10 recent posts from the last 30 days on each platform that supports a look-back, so the first search is rarely empty. ### cURL [Guide →](https://docs.mentio.dev/quickstart) ``` curl "https://api.mentio.dev/v1/mentions?platform=reddit&relevant=true&limit=25" \ -H "Authorization: Bearer $MENTIO_API_KEY" ``` ### TypeScript [Guide →](https://docs.mentio.dev/sdks/typescript) ``` import { createMentio } from '@mentio-dev/sdk'; const mentio = createMentio({ apiKey: process.env.MENTIO_API_KEY! }); // Track a keyword on two platforms. await mentio.createKeyword({ body: { term: 'acme cloud', kind: 'brand', platforms: ['reddit', 'x'] }, }); // Read what arrived, relevant posts only, newest first. const { data } = await mentio.searchMentions({ query: { platform: 'reddit', relevant: true, limit: 25 }, throwOnError: true, }); for (const m of data.data) { console.log(m.post.platform, m.classification?.relevance, m.classification?.intents, m.post.url); } ``` ### Python [Guide →](https://docs.mentio.dev/sdks/python) ``` from mentio import Mentio mentio = Mentio(api_key="mk_live_...") mentio.keywords.create(term="acme cloud", kind="brand", platforms=["reddit", "x"]) for m in mentio.mentions.search(intent="buy_intent", relevant=True, limit=25).data: print(m.post.platform.value, m.classification.relevance, m.post.url) ``` ### CLI [Guide →](https://docs.mentio.dev/cli) ``` mentio auth:login mentio keywords:create --term "acme cloud" --kind brand --platforms reddit,x mentio mentions:search --relevant true --intent buy_intent --limit 20 mentio mentions:watch --platform reddit | jq -r '.post.url' ``` One mention, abridged ``` { "id": "mm_7f3a...", "status": "open", "relevant": true, "keyword": { "id": "kw_60d9...", "term": "acme cloud" }, "post": { "platform": "reddit", "url": "https://www.reddit.com/r/devops/comments/...", "text": "We're evaluating acme cloud vs the incumbent, anyone switched?", "publishedAt": "2026-09-03T08:12:44.000Z" }, "author": { "handle": "u/ops_lead", "followers": 1240 }, "classification": { "relevance": 92, "sentiment": "neutral", "intents": ["buy_intent", "comparison"], "note": "Evaluating acme cloud against a competitor for a team." } } ``` The full shape, with engagement, links, reviews, confidence and triage, is in the [Mentions reference](https://docs.mentio.dev/api/mentions/get-mention). ## How do you get mentions pushed to you? Create a webhook channel, then attach an alert rule with a filter and an event name: "negative mentions", "buying signals on Reddit", "anything linking to our docs". Every mention that passes the rule is POSTed to your URL right after it is scored, or once a day as a digest. Each request carries `X-Mentions-Timestamp` and `X-Mentions-Signature-V2`, an HMAC-SHA256 of the timestamp and the raw body with your channel's secret, so a captured delivery cannot be replayed. A retry keeps the same id; deduplicate on it. [Webhook guide →](https://docs.mentio.dev/webhooks) Verify a delivery (Node) ``` import { createHmac, timingSafeEqual } from 'node:crypto'; export function verify(rawBody: Buffer, headers: Record, secret: string) { const timestamp = Number(headers['x-mentions-timestamp']); const signature = headers['x-mentions-signature-v2'] ?? ''; if (!Number.isInteger(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > 300) return false; const expected = 'v2=' + createHmac('sha256', secret).update(`${timestamp}.`).update(rawBody).digest('hex'); return expected.length === signature.length && timingSafeEqual(Buffer.from(expected), Buffer.from(signature)); } ``` ## Auth, limits and the rest of the contract Base URL https://api.mentio.dev/v1. JSON in and out, ISO 8601 timestamps, prefixed ids, one OpenAPI 3 document. Authentication A Bearer API key (mk\_live\_...), read or write scope, optional expiry, shown once and stored hashed. MCP clients can sign in with OAuth instead. Rate limit 600 requests a minute per workspace, across every key and token, with X-RateLimit headers and a 429 plus Retry-After past it. Dashboard traffic does not count. Errors One catalog of stable codes (rate\_limited, insufficient\_balance, not\_found...) with the HTTP status and a request id to quote to support. Webhooks Signed with HMAC-SHA256 over the timestamp and raw body (X-Mentions-Signature-V2), retried with the same id, logged per delivery. Platforms X, Reddit, Hacker News, GitHub, Bluesky, LinkedIn, Stack Overflow, DEV, YouTube, TikTok, Instagram, Facebook, news, App Store, Google Play, Trustpilot and Google Maps. ## How much does the API cost? There is no API plan and no seat price. You pay **$5 per tracked keyword a month** and **$0.008 per matched mention**, from a prepaid balance. API calls, webhooks, alerts and MCP tool calls are not billed on top. Every account starts with $5.80 of credit and no card: one keyword for a month plus 100 mentions. A keyword can carry a mention cap per day, week or month, so a reseller can sell tracking at a fixed price, and `GET /v1/usage/breakdown` returns the cost of every keyword over 7, 30 or 90 days or a calendar month. [Pricing and a cost calculator →](/pricing/) ## Which client should you use? The SDKs and the CLI are generated from the OpenAPI document and the MCP tools share its schemas, so none of them falls behind the API. [ TypeScript SDK @mentio-dev/sdk on npm, typed, no runtime dependencies. ](https://docs.mentio.dev/sdks/typescript)[ Python SDK pip install mentio, sync and async, typed. ](https://docs.mentio.dev/sdks/python)[ CLI Every endpoint as a noun:verb command, plus a live mentions feed. ](https://docs.mentio.dev/cli)[ MCP server 56 tools for Claude, Cursor, Codex and ChatGPT at https://mcp.mentio.dev/mcp. ](/agents/)[ Reddit MCP The same server, pointed at Reddit, with no Reddit API keys. ](/reddit-mcp/)[ OpenAPI document Generate a client in any language from the spec. ](https://api.mentio.dev/v1/openapi.json) [ Open source Mentio OS: a dashboard to fork An MIT-licensed social listening dashboard in Next.js and shadcn/ui, built only on the public API. Fork it and ship it to your own customers under your brand. ](https://github.com/mentio-dev/mentio-os)[ Migrating Coming from Octolens? An Octolens-compatible endpoint lets existing integrations move by changing the base URL and the key. ](https://docs.mentio.dev/migrate/octolens) [ Guide Social listening vs social media monitoring: the difference ](/blog/social-listening-vs-social-monitoring/)[ Tools The best social listening tools in 2026, compared ](/blog/best-social-listening-tools/)[ Platforms Reddit API in 2026: keys, limits, pricing and alternatives ](/blog/reddit-api-pricing/) ## Social listening API questions What is a social listening API? An API that watches public platforms for the keywords you choose and returns the posts that mention them, so your own code can store, analyze or act on them. Mentio watches your keywords on its side, scores every match for relevance, sentiment and intent, and serves the result over REST, signed webhooks, SDKs, a CLI and an MCP server. Which platforms does the API cover? X, Reddit, Hacker News, GitHub, Bluesky, LinkedIn, Stack Overflow, DEV, YouTube, TikTok, Instagram, Facebook, news, App Store, Google Play, Trustpilot and Google Maps. A keyword can be searched on every platform or only some, and app and place reviews are connected per keyword. One request searches all of them together. Is there a brand monitoring or mentions API on every plan? There are no plans. Every account gets the full API, the webhooks, the SDKs and the MCP server. You pay $5 per tracked keyword a month and $0.008 per matched mention from a prepaid balance; API calls are not billed. Every account starts with $5.80 of free credit, no card. What are the API rate limits? 600 requests a minute per workspace, counted across every API key and OAuth token on a sliding window, MCP tool calls included. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; past the limit you get a 429 with Retry-After. The two CSV exports have their own cap of 6 a minute. Can I get mentions pushed to me instead of polling? Yes. Create a webhook channel and attach an alert rule with a filter: every mention that passes it is POSTed to your URL right after it is scored, or once a day as a digest. Each request is signed with HMAC-SHA256 over the timestamp and body, and a retry keeps the same id so you can deduplicate. Can I build my own dashboard on it? Yes. Mentio OS is an open-source (MIT) social listening dashboard built only on the public API, in Next.js and shadcn/ui, on GitHub at mentio-dev/mentio-os. Fork it, point it at your API key and ship it under your own brand. ## Start monitoring brand mentions One request tracks your first keyword. The first scored mention lands within minutes, in Slack, a webhook, or your agent. [Get your API key ›](https://app.mentio.dev/login?mode=signup)[Read the docs ›](https://docs.mentio.dev) $5.80 free credit · no card · no subscription