# Rumoro

> Rumoro is social listening for developers and AI agents. You give it keywords, and it finds them on X, Bluesky, Hacker News, Reddit, GitHub, Stack Overflow, DEV, YouTube, LinkedIn, TikTok, Instagram and in the news, and in App Store, Google Play, Trustpilot and Google reviews. Each mention gets a relevance score, a sentiment and intents. You get them through a REST API, TypeScript and Python SDKs, a CLI, an MCP server, signed webhooks, Slack, Telegram and email.

Each page below is also available as Markdown at its link, and the whole site is in https://docs.rumoro.dev/llms-full.txt. The API is described in https://api.rumoro.dev/v1/openapi.json.

## Use Rumoro when

- someone wants to know what people say online about their product, brand, a competitor or a topic, or wants to be alerted in Slack, Telegram, email or a webhook
- mentions need scoring (relevance from 0 to 100, sentiment, intents like buy intent, question, complaint, praise or comparison) or triage (open, ignored, done, assigned, snoozed)
- someone wants the people behind the mentions, or their share of voice compared with competitors
- someone asks for Rumoro, its API, SDKs, CLI or MCP server

Rumoro only reads public posts and reviews. It doesn't read private or paid content, and it never posts or replies.

## Connect

- The REST API is at https://api.rumoro.dev/v1. Send `Authorization: Bearer ref_...` with a key that a person creates on the API keys page at https://app.rumoro.dev.
- The MCP server is at https://mcp.rumoro.dev/mcp (streamable HTTP), with its server card at https://mcp.rumoro.dev/.well-known/mcp/server-card.json. Connecting and `tools/list` work without a credential, and every `tools/call` needs one. Clients that support MCP authorization sign in through the browser. Other clients send an API key.
- A read-only documentation MCP server needs no key. It is at https://docs.rumoro.dev/api/mcp, with its card at https://docs.rumoro.dev/.well-known/mcp.json, and has the tools search_docs, read_page and list_pages.
- The SDKs are `@rumoro-dev/sdk` on npm and `rumoro` on PyPI. The CLI runs with `npx @rumoro-dev/cli`.
- The agent guide is at https://mcp.rumoro.dev/mcp/guide and is also an MCP resource.
- New endpoints, fields and enum values are added to `/v1`, so ignore what you don't know. Breaking changes will come as `/v2`, with `/v1` kept for at least six months (https://docs.rumoro.dev/conventions.mdx).
- The changelog lists the newest changes first at https://docs.rumoro.dev/changelog, also as Markdown (https://docs.rumoro.dev/changelog.mdx) and RSS (https://docs.rumoro.dev/changelog/rss.xml).

## Guides

- [Overview](https://docs.rumoro.dev/index.mdx): What Rumoro does, how a post becomes a mention in your feed, and how to build on it.
- [Alerts and channels](https://docs.rumoro.dev/alerts.mdx): Alert rules choose which mentions you hear about and how often. Channels are Slack, Telegram, email or a webhook.
- [Slack integration](https://docs.rumoro.dev/alerts/slack.mdx): Get relevant mentions in a Slack channel, with buttons to open, close or mute them.
- [Telegram integration](https://docs.rumoro.dev/alerts/telegram.mdx): Mention alerts and digests, posted by a Telegram bot to you or your team's group.
- [Authentication](https://docs.rumoro.dev/authentication.mdx): How to authenticate with an API key or OAuth, what read and write scopes allow, and how to manage keys.
- [Billing](https://docs.rumoro.dev/billing.mdx): How Rumoro's prepaid balance works, what keywords and mentions cost, and how to read your wallet and ledger through the API.
- [Changelog](https://docs.rumoro.dev/changelog.mdx): What changed in Rumoro, newest first. Also as an RSS feed.
- [CLI](https://docs.rumoro.dev/cli.mdx): @rumoro-dev/cli on npm. The Rumoro API in your terminal, with browser sign-in, a live mention feed and MCP setup.
- [Account](https://docs.rumoro.dev/cli/account.mdx): Manage keys, billing, the team and sign-in, set up MCP and check the API.
- [Alerts and attention](https://docs.rumoro.dev/cli/alerts.mdx): Create alerts and channels, test them, and handle attention items.
- [Analytics](https://docs.rumoro.dev/cli/analytics.mdx): Summary, series, breakdown, share of voice and reviews for one period.
- [Keywords and groups](https://docs.rumoro.dev/cli/keywords.mdx): Create and adjust keywords, organize them in groups, and set workspace filters.
- [Mentions and views](https://docs.rumoro.dev/cli/mentions.mdx): Find, handle and export mentions, watch new ones arrive, and save views.
- [People and segments](https://docs.rumoro.dev/cli/people.mdx): Work with the people who post about you, log outreach, and save segments.
- [Conventions](https://docs.rumoro.dev/conventions.mdx): Paths, ids, methods, paging, filters, errors and versions. The patterns that hold across the whole Rumoro API.
- [Errors](https://docs.rumoro.dev/errors.mdx): The error envelope and the stable error codes, with what each one means and what to do.
- [Needs attention](https://docs.rumoro.dev/guides/attention.mdx): Rumoro checks every hour for spikes, negative turns, noisy keywords and failing channels, and tells you where you want.
- [Keyword groups](https://docs.rumoro.dev/guides/groups.mdx): Organise keywords by customer, campaign or product, track the same word for several of them, and see each group's cost.
- [Keyword health](https://docs.rumoro.dev/guides/keyword-health.mdx): See which keywords cost more than they're worth, where their noise comes from, and fix them with one PATCH.
- [Views](https://docs.rumoro.dev/guides/views.mdx): Save a mention filter under a name. Switch to it in the dashboard, read it with viewId, or export it as CSV or JSON.
- [How it works](https://docs.rumoro.dev/how-it-works.mdx): How Rumoro collects posts, how often it checks each platform, which rules filter them, and what happens to a mention.
- [OpenClaw](https://docs.rumoro.dev/integrations/openclaw.mdx): Add the Rumoro skill to OpenClaw and ask it in plain words for your mentions, keywords, alerts and numbers.
- [MCP server](https://docs.rumoro.dev/mcp.mdx): Connect Claude Code and other MCP clients to your mentions. Sign in with OAuth or use an API key.
- [Tools](https://docs.rumoro.dev/mcp/tools.mdx): All 55 MCP tools by area, with what each one does.
- [Migrate from Octolens](https://docs.rumoro.dev/migrate/octolens.mdx): Switch from Octolens by changing two settings, copy your keywords, feeds and filters with one script, and move your alerts.
- [Platforms](https://docs.rumoro.dev/platforms.mdx): Which platforms Rumoro searches, how often, and what a new keyword finds on its first day.
- [App Store](https://docs.rumoro.dev/platforms/appstore.mdx): New App Store reviews of your apps, per country, with their star rating.
- [Bluesky](https://docs.rumoro.dev/platforms/bluesky.mdx): Public Bluesky posts with your keyword, picked up within seconds.
- [DEV](https://docs.rumoro.dev/platforms/devto.mdx): New articles on DEV (dev.to) with your keyword in the title, description or tags.
- [GitHub](https://docs.rumoro.dev/platforms/github.mdx): Public GitHub issues and pull requests with your keyword in the title or body.
- [Google reviews](https://docs.rumoro.dev/platforms/googlemaps.mdx): New Google reviews of your shop, restaurant, office or any other place on Google Maps, with their star rating.
- [Google Play](https://docs.rumoro.dev/platforms/googleplay.mdx): New Google Play reviews of your apps, per country and language, with their star rating.
- [Hacker News](https://docs.rumoro.dev/platforms/hackernews.mdx): Hacker News stories and comments with your keyword, searched every 5 minutes.
- [Instagram](https://docs.rumoro.dev/platforms/instagram.mdx): Public Instagram posts and reels with your keyword in the caption or hashtag. No Instagram login needed.
- [LinkedIn](https://docs.rumoro.dev/platforms/linkedin.mdx): Find your keyword in public LinkedIn posts by people and companies.
- [News](https://docs.rumoro.dev/platforms/news.mdx): English-language news articles with your keyword in the headline or among the people and organisations they name.
- [Reddit](https://docs.rumoro.dev/platforms/reddit.mdx): Reddit posts with your keyword, from every subreddit.
- [Reviews](https://docs.rumoro.dev/platforms/reviews.mdx): How a keyword collects reviews from the App Store, Google Play, Trustpilot and Google.
- [Stack Overflow](https://docs.rumoro.dev/platforms/stackoverflow.mdx): Stack Overflow questions and answers with your keyword, checked every hour.
- [TikTok](https://docs.rumoro.dev/platforms/tiktok.mdx): New TikTok videos with your keyword in the caption, with views and likes.
- [Trustpilot](https://docs.rumoro.dev/platforms/trustpilot.mdx): New Trustpilot reviews of your company, with their star rating.
- [X](https://docs.rumoro.dev/platforms/x.mdx): Posts and replies on X that mention your keyword, with engagement and author details.
- [YouTube](https://docs.rumoro.dev/platforms/youtube.mdx): New YouTube videos with your keyword in the title or description.
- [Quickstart](https://docs.rumoro.dev/quickstart.mdx): Create a keyword, describe your company, find mentions and mark one done. Five API calls.
- [Rate limits](https://docs.rumoro.dev/rate-limits.mdx): Each workspace can make 600 requests a minute. How the limit is counted, which headers show it, and how to handle a 429.
- [SDKs](https://docs.rumoro.dev/sdks.mdx): Official TypeScript and Python clients for the Rumoro API, or generate one from the OpenAPI document.
- [Python SDK](https://docs.rumoro.dev/sdks/python.mdx): rumoro on PyPI. Every Rumoro API operation from Python, sync and async.
- [TypeScript SDK](https://docs.rumoro.dev/sdks/typescript.mdx): @rumoro-dev/sdk on npm. One typed function for each Rumoro API operation.
- [Webhooks](https://docs.rumoro.dev/webhooks.mdx): Get mentions and digests as signed requests to your own URL. Setup, retries, signature checks and every event.
- [Account events](https://docs.rumoro.dev/webhooks/account-events.mdx): Webhooks for changes to keywords, your balance and things that need attention, which are not tied to a mention.
- [Digest events](https://docs.rumoro.dev/webhooks/digest-events.mdx): The summary an hourly, daily or weekly rule sends each period, field by field.
- [Mention events](https://docs.rumoro.dev/webhooks/mention-events.mdx): The request an instant rule sends for each new mention, field by field.

## API reference

- [Introduction](https://docs.rumoro.dev/api.mdx): Every Rumoro endpoint, generated from the OpenAPI document the API serves.
- [Create a keyword](https://docs.rumoro.dev/api/keywords/create-keyword.mdx): Starts monitoring a word or phrase. Matching, scoring and delivery start with the next poll. A workspace with balance can have up to 500 keywords, each costing $5 a month, taken from the balance day by day. `matching` narrows what counts as a match, with required and excluded terms, excluded authors and case, before anything is stored, so rejected posts are never billed. `context` is a sentence only this keyword's classifier reads. `cap` limits matched mentions per month. At the cap the keyword stops matching until the 1st of next month (UTC) or until you raise the cap, and its daily charge continues.
- [Delete a keyword](https://docs.rumoro.dev/api/keywords/delete-keyword.mdx): Deletes the keyword with its matches. A post that another keyword also matched is kept.
- [Check a keyword's health](https://docs.rumoro.dev/api/keywords/get-keyword-health.mdx): Checks whether the keyword earns its cost over `range` (default 30d). Returns a status (healthy, noisy, quiet, capped, paused or new) with plain-word reasons, numbers by platform and week, cost, the words and authors behind the noise, and suggestions. Send a suggestion's `patch` unchanged to PATCH /v1/keywords/{id}. Its effect comes from replaying the matcher's rules on the window's posts. `ai=true` adds a model-written context (cached a day, up to 20 model calls an hour per workspace). Read only and never billed. Reports are cached 5 minutes and rebuilt after a keyword change. Up to 30 reads a minute per workspace.
- [Get a keyword](https://docs.rumoro.dev/api/keywords/get-keyword.mdx): Returns one keyword with its matching rules, review pages, this month's cost and the polling status on each platform.
- [List keywords](https://docs.rumoro.dev/api/keywords/list-keywords.mdx): Returns the workspace's keywords with their match counts and polling status. With no parameters you get all keywords, latest first. `q` searches the term and context. `kind`, `status` and `platform` filter the list, `sort` orders it, and `limit` and `offset` page through it. `total` is the number of matching keywords before paging.
- [Update a keyword](https://docs.rumoro.dev/api/keywords/update-keyword.mdx): Mutes or unmutes the keyword, or changes its `kind`, platforms, classifier `context`, `matching` rules or monthly mention `cap`. Each rule field is optional and an empty list clears it. A null cap removes the cap, and a cap above this month's count resumes a capped keyword right away. New rules apply to mentions from the next poll on. Stored mentions stay as they are.
- [Export mentions as CSV](https://docs.rumoro.dev/api/mentions/export-mentions-csv.mdx): Returns as CSV the mentions GET /v1/mentions lists for the same filters. Rows are ordered by match time, latest first, which is the order they reached your feed and can differ from the post date. The columns are id, published_at, platform, keyword, author, author_url, author_followers, relevance, sentiment, intents (separated by |), language, confidence, status, relevant, delivered, url, links (separated by |), text (the first 1,000 characters), group, group_external_id, rating and app_id (reviews only), and title and image_url (on platforms that have them). The file holds at most 10,000 rows, and the X-Mentions-Truncated header tells you when rows were cut. Each workspace can export 6 times a minute, and a 429 includes Retry-After.
- [Export mentions as JSON](https://docs.rumoro.dev/api/mentions/export-mentions-json.mdx): Returns in one response the mentions GET /v1/mentions lists for the same filters, latest match first, which is the order they reached your feed. Each row is the full Mention object from the list, text included. At most 10,000 mentions are returned, and `truncated` tells you when some were cut. It shares the CSV export's limit of 6 exports a minute per workspace, in either format, and a 429 includes Retry-After.
- [Get a mention](https://docs.rumoro.dev/api/mentions/get-mention.mdx): Fetches one mention by id, with the same fields the list returns. An id from another workspace gets a 404.
- [List mentions](https://docs.rumoro.dev/api/mentions/search-mentions.mdx): 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.
- [Update a mention](https://docs.rumoro.dev/api/mentions/update-mention.mdx): 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.
- [Get the company profile](https://docs.rumoro.dev/api/company/get-company.mdx): Returns what the classifier knows about your company. That is the name, description, use cases and your accounts, plus the context text built from them.
- [Update the company profile](https://docs.rumoro.dev/api/company/update-company.mdx): Changing profile fields rebuilds the classifier's context. Setting `context` yourself replaces it until the next profile change. New mentions are scored with the change right away.
- [Create an API key](https://docs.rumoro.dev/api/api-keys/create-api-key.mdx): Issues a new API key in this workspace. The key is shown only in this response, and only its hash is stored. `expiresAt` makes it stop working at a set time, useful for a contractor or a one-off script. An expired key stays in the list until you revoke it.
- [List API keys](https://docs.rumoro.dev/api/api-keys/list-api-keys.mdx): Lists the workspace's active keys, latest first, with name, prefix, scope, expiry and last use. Revoked keys and secrets are never listed.
- [Revoke an API key](https://docs.rumoro.dev/api/api-keys/revoke-api-key.mdx): Revokes the key. The API refuses it right away, and cached checks catch up within a few minutes.
- [Get Health](https://docs.rumoro.dev/api/system/get-health.mdx): Checks that the API is up. Needs no key and is not rate limited. Returns `ok: true` with the state of the database and each background worker.
- [Create an alert](https://docs.rumoro.dev/api/alerts/create-alert.mdx): Creates an alert, which pairs a filter with one or more channels. instant mode sends each matching mention as it arrives. hourly sends a digest of the previous full UTC hour at five past, skips hours with no mention above the rule's minimum, takes no schedule and works with Slack, Telegram and webhook channels only. daily sends one digest at schedule.hour in schedule.timezone. weekly sends one a week on schedule.weekday, from 0 for Sunday to 6 for Saturday. filter.anyOf adds OR logic with groups of mention-list conditions. At least one group must match, as well as the rest of the filter.
- [Create a channel](https://docs.rumoro.dev/api/alerts/create-channel.mdx): Creates a webhook (the default), email or Slack channel. Slack needs a connected workspace, otherwise 409. Telegram chats are connected in the dashboard. A webhook's signing secret appears only in this response.
- [Delete an alert](https://docs.rumoro.dev/api/alerts/delete-alert.mdx): Deletes the alert and its delivery history. Its channels stay.
- [Delete a channel](https://docs.rumoro.dev/api/alerts/delete-channel.mdx): Deletes the channel and takes it off its alerts. Queued sends to it are cancelled. The alerts stay.
- [Get an alert](https://docs.rumoro.dev/api/alerts/get-alert.mdx): Returns one alert with its filter, mode, schedule, channels and delivery stats.
- [Get a channel](https://docs.rumoro.dev/api/alerts/get-channel.mdx): Returns one channel with its settings, account events and delivery stats. A webhook's signing secret is never shown here.
- [List alerts](https://docs.rumoro.dev/api/alerts/list-alerts.mdx): Lists the workspace's alerts, latest first, each with its filter, mode, schedule and channels.
- [List a channel's deliveries](https://docs.rumoro.dev/api/alerts/list-channel-deliveries.mdx): Lists the mentions, digests and account events sent to the channel, latest first, with status and the last error. `limit` defaults to 50, up to 200.
- [List channels](https://docs.rumoro.dev/api/alerts/list-channels.mdx): Lists the workspace's channels with their settings and delivery stats.
- [Mute authors](https://docs.rumoro.dev/api/alerts/mute-alert-authors.mdx): Adds authors to the alert's muted list and leaves the rest of its filter alone. Links are handled as in the dashboard, so a post link mutes its author, twitter.com turns into x.com and a Hacker News profile keeps its id. Authors who are already muted are skipped, so retrying is safe. An entry that is not a person, such as a subreddit or a story, fails the request and the error names it.
- [Rotate the signing secret](https://docs.rumoro.dev/api/alerts/rotate-webhook-secret.mdx): Gives a webhook channel a new signing secret, shown only in this response. The old secret stops working at once.
- [Send a digest now](https://docs.rumoro.dev/api/alerts/run-alert-digest.mdx): Sends the digest for the alert's last hour, day or week now and returns each channel's outcome. Works on digest alerts only, and the schedule doesn't change.
- [Test an alert](https://docs.rumoro.dev/api/alerts/test-alert.mdx): Sends a test message to each of the alert's channels now and returns each outcome. Webhooks receive the event `test`.
- [Test a channel](https://docs.rumoro.dev/api/alerts/test-channel.mdx): Sends a test message to the channel now and returns the outcome. Webhooks receive the event `test`.
- [Unmute authors](https://docs.rumoro.dev/api/alerts/unmute-alert-authors.mdx): Takes authors off the muted list, keeping the rest of the filter. Each entry can be the stored value or any link to the person's profile or posts. Retrying is safe, because authors who aren't muted are skipped.
- [Update an alert](https://docs.rumoro.dev/api/alerts/update-alert.mdx): Changes an alert. `filter` and `channelIds` replace the old values. Queued digests are cancelled, as are queued sends to a removed channel or from a disabled alert.
- [Update a channel](https://docs.rumoro.dev/api/alerts/update-channel.mdx): Changes a channel's label and account events, and a webhook's URL and headers. `headers` and `events` replace the old values.
- [Get a mention breakdown](https://docs.rumoro.dev/api/analytics/get-analytics-breakdown.mdx): `by` sets the rows (platform, keyword, sentiment, intent, status, hour as weekday and hour, or person), and each row has matched, relevant and sentiment counts. Pick the period with `range` (7d, 30d, 90d or 365d up to today) or with `from` and `to`. Days follow `timezone`, UTC by default. `keywordIds` and `platforms` narrow the data, and `compare=true` adds the equally long period just before. Dates are publish dates.
- [Mentions over time](https://docs.rumoro.dev/api/analytics/get-analytics-series.mdx): Returns matched, relevant and sentiment counts per day or week over the period. You get one total series, or one per platform or keyword with `by`. Pick the period with `range` (7d, 30d, 90d or 365d up to today) or with `from` and `to`. Days follow `timezone`, UTC by default. `keywordIds` and `platforms` narrow the data, and `compare=true` adds the equally long period just before. Dates are publish dates.
- [Get summary counts](https://docs.rumoro.dev/api/analytics/get-analytics-summary.mdx): Returns matched and relevant mentions, unique posts and people, sentiment, buying intent and questions, estimated reach, and the triage status of the matches. Pick the period with `range` (7d, 30d, 90d or 365d up to today) or with `from` and `to`. Days follow `timezone`, UTC by default. `keywordIds` and `platforms` narrow the data, and `compare=true` adds the equally long period just before. Dates are publish dates.
- [Get review stats](https://docs.rumoro.dev/api/analytics/get-reviews-report.mdx): Returns stats on reviews your keywords collect from the App Store, Google Play, Trustpilot and Google Maps. You get the count, average stars, the star distribution, replies and open 1 and 2 star reviews, for the workspace and per review page. Each page has a series of average stars per `bucket`, and the report lists the tags of unhappy reviews. Two keywords matching one review count it once. Pick the period with `range` (7d, 30d, 90d or 365d up to today) or with `from` and `to`. Days follow `timezone`, UTC by default. `keywordIds` and `platforms` narrow the data, and `compare=true` adds the equally long period just before. Dates are publish dates.
- [Get share of voice](https://docs.rumoro.dev/api/analytics/get-share-of-voice.mdx): Returns each keyword with matches in the period, its counts and its share of all brand and competitor matches. Topic keywords are counted but not part of the split. Pick the period with `range` (7d, 30d, 90d or 365d up to today) or with `from` and `to`. Days follow `timezone`, UTC by default. `keywordIds` and `platforms` narrow the data, and `compare=true` adds the equally long period just before. Dates are publish dates.
- [Dismiss an attention item](https://docs.rumoro.dev/api/attention/dismiss-attention.mdx): Dismisses an item. It leaves the open list and stays away while its condition lasts. After the condition ends, a new episode can open a new item. Calling it twice has the same effect as once.
- [List attention items](https://docs.rumoro.dev/api/attention/list-attention.mdx): Lists items that need a person, latest first. Kinds are mention.spike (a keyword's mentions jumped in the last hour), sentiment.negative_spike (its 24-hour negative share jumped), keyword.noisy (it turned noisy) and channel.failing (a channel's recent sends all failed). Checks run hourly. Items open when the condition starts and resolve when it ends. Open items are the default, and `status=all` adds the history. Opening an item also sends an account event of the same name to subscribed webhook, Slack, email and Telegram channels.
- [Check the credential](https://docs.rumoro.dev/api/auth/whoami.mdx): Call this first. It shows the workspace the credential works in, its type (API key, MCP sign-in token or dashboard session), whether it can write, and for keys the id and expiry. A read key gets 403 read_only_key on any write, and scripts often aim at the wrong workspace.
- [Start a top-up](https://docs.rumoro.dev/api/billing/create-top-up.mdx): Returns a hosted checkout link with `amountCents` filled in. The buyer can change it there, from $20 to $5,000. The balance is credited within a minute of payment, and tracking paused for balance resumes right away. This call charges nothing by itself. `successUrl` must be on an origin this deployment trusts. Leave it out to return to the dashboard's billing page.
- [Get a receipt link](https://docs.rumoro.dev/api/billing/get-invoice-url.mdx): For a paid order from GET /v1/billing/invoices, returns a receipt PDF URL that expires soon.
- [Get the balance](https://docs.rumoro.dev/api/billing/get-wallet.mdx): Returns every detail of the prepaid balance. That covers the ledger total, pending mention charges, the effective balance used for pausing, the daily spend and days left, running and paused keywords, the cost of a day and of resuming, the welcome credit, the latest top-up, the top-up limits and the auto-recharge settings. `GET /v1/usage` gives a shorter version.
- [List receipts](https://docs.rumoro.dev/api/billing/list-invoices.mdx): Returns the top-up orders, latest first, as Polar, the merchant of record, stores them. You get this workspace's orders among the billing customer's latest 100. No orders exist before the first top-up.
- [List ledger entries](https://docs.rumoro.dev/api/billing/list-ledger.mdx): Shows the balance's history, latest first. Entries cover the welcome credit, top-ups, refunds, adjustments, and the daily keyword-day and mention debits. Debits carry their UTC settlement day and cumulative units. Cursor pages.
- [Get the workspace filters](https://docs.rumoro.dev/api/filters/get-filters.mdx): Returns the workspace noise rules, applied to every keyword before a mention is stored. They exclude terms, authors and GitHub repositories, and allow or block subreddits. Rejected posts are never classified, sent or billed. Keywords add their own `matching` rules on top.
- [Update the workspace filters](https://docs.rumoro.dev/api/filters/update-filters.mdx): Sets new values for any of the lists. A list you leave out stays as it is, and an empty list clears it. Rumoro normalizes each entry. Terms become lowercase, authors profile links or plain names, repositories owner/name, and subreddits lose the r/. New mentions follow the change within a minute. Stored mentions stay as they are.
- [Create a group](https://docs.rumoro.dev/api/groups/create-group.mdx): Creates a keyword group. `name` must be unique in the workspace. `externalId` is optional and also unique. It is your own id, such as a client id, so you can find the group without storing ours. `context` is optional. It is a company description for this group, which the classifier reads instead of the workspace profile for the group's keywords. Then send the group's id as `groupId` when you create a keyword.
- [Delete a group](https://docs.rumoro.dev/api/groups/delete-group.mdx): Deletes the group and all of its keywords, each as DELETE /v1/keywords/{id} would. Their mentions are deleted too, alert rules that named them are updated, and past charges stay in the usage record. Read the group first, since `stats.keywords` tells you how many keywords will be deleted. Only non-default groups can be deleted.
- [Get a group](https://docs.rumoro.dev/api/groups/get-group.mdx): Returns one keyword group with its external id and keyword counts.
- [List groups](https://docs.rumoro.dev/api/groups/list-groups.mdx): Returns the workspace's keyword groups, the default group first and then the oldest. Groups organize keywords, for example by client, campaign or product. Every keyword is in one group, a group can hold a term once, and GET /v1/usage/breakdown?by=group shows each group's cost. `externalId` looks a group up by your own id.
- [Update a group](https://docs.rumoro.dev/api/groups/update-group.mdx): Changes a group's name, your `externalId` for it or its company description in `context`. Null clears externalId. Null clears context too, so the workspace profile applies again. New mentions use the new context right away, and older ones are not scored again. You can rename the default group, but it takes no description, because it is the workspace itself and uses the company profile.
- [Invite a member](https://docs.rumoro.dev/api/members/create-invitation.mdx): Invites an address by email as admin or member. Invitations expire after 48 hours. Repeating it for a pending address returns that invitation with 200 and sends nothing. Existing members get 409 already_member. Needs a signed-in owner or admin (dashboard session or MCP sign-in token). API keys get 403.
- [List pending invitations](https://docs.rumoro.dev/api/members/list-invitations.mdx): Returns invitations that have not been accepted, declined or expired yet. Once accepted, the person shows up in GET /v1/members.
- [List members](https://docs.rumoro.dev/api/members/list-members.mdx): Returns all workspace members, owners first. Use `userId` for a mention's assigneeId and a person's ownerId.
- [Remove a member](https://docs.rumoro.dev/api/members/remove-member.mdx): Needs a signed-in owner or admin. Admins can't remove owners, and the last owner can't be removed at all (409 last_owner). Access ends within a minute, at the next dashboard request or when the OAuth token's short cache expires. The member's mentions, notes and outreach records remain.
- [Revoke an invitation](https://docs.rumoro.dev/api/members/revoke-invitation.mdx): Cancels the invitation, and its email link stops working right away. Needs a signed-in owner or admin. An API key gets 403.
- [Delete outreach](https://docs.rumoro.dev/api/people/delete-person-activity.mdx): Deletes an activity that was logged by mistake. The person keeps the same owner and stage.
- [Export people as CSV](https://docs.rumoro.dev/api/people/export-people-csv.mdx): Returns as CSV the people GET /v1/people lists for the same filters, segmentId included. Each row is one person with handle, followers, email, website, company, location and tags, then outreach stage, owner and last contacted. The file holds at most 5,000 people. Each workspace can export 6 times a minute, and a 429 includes Retry-After.
- [Get a person](https://docs.rumoro.dev/api/people/get-person.mdx): Fetches a person, with your workspace's own data on them. The id of a merged account returns the person it was merged into.
- [List people](https://docs.rumoro.dev/api/people/list-people.mdx): Returns the authors of your mentions, one row per person. Each row has their accounts, reach, public profile, stats for this workspace, your notes and tags, and your outreach status. You can filter by platform, tag, follower range, mention counts, intents, keyword kinds they did or did not mention, outreach stage, owner, automated (bots whose matched posts are mostly machine-made) or a saved segment. Pages use offset and include a total.
- [List outreach activities](https://docs.rumoro.dev/api/people/list-person-activities.mdx): Returns up to 200 logged contacts with this person over all their accounts, latest first. Each shows who reached out, the channel, the time and a short note. Check it before you reach out, so two teammates don't contact the same person unaware.
- [Log outreach](https://docs.rumoro.dev/api/people/log-person-activity.mdx): Logs a contact with this person, such as an email, a direct message or a call. A not_contacted person moves to contacted. A person with no owner gets the contacting member as owner. A later stage or an existing owner is left alone. `memberId` falls back to the signed-in member. An API-key request without memberId logs an activity with no member, so no owner is set.
- [Merge people](https://docs.rumoro.dev/api/people/merge-people.mdx): Marks this account and another person as the same individual, in your workspace only. The person in `into` receives the mentions, tags, notes and outreach activities, and keeps its owner and stage, taking the other's where it has none.
- [Split a person](https://docs.rumoro.dev/api/people/split-person.mdx): Reverses a merge, so the account is a separate person again.
- [Update a person](https://docs.rumoro.dev/api/people/update-person.mdx): Changes your workspace's tags, notes and mute for the person, and the outreach owner and stage. The owner must be a workspace member, and null removes it. Muting hides their posts from your feed and all channels. Collection and billing do not change.
- [Create a segment](https://docs.rumoro.dev/api/segments/create-segment.mdx): Saves a people filter under a name. Names are unique in the workspace (409). The response says how many people match now.
- [Delete a segment](https://docs.rumoro.dev/api/segments/delete-segment.mdx): Deletes the segment. The people in it are not changed.
- [Get a segment](https://docs.rumoro.dev/api/segments/get-segment.mdx): Returns one segment with its filter and how many people match it now.
- [List segments](https://docs.rumoro.dev/api/segments/list-segments.mdx): Returns your saved segments with the current number of people in each, plus presets you can save as a start. Segments are counted on each read and never stored as lists. To see who is in one, send its id to GET /v1/people.
- [Update a segment](https://docs.rumoro.dev/api/segments/update-segment.mdx): Changes a segment's name, description or filter. A new filter replaces the old one completely.
- [Get the usage breakdown](https://docs.rumoro.dev/api/usage/get-usage-breakdown.mdx): Returns what the workspace used and was charged over a period, in US cents at list price. Each call groups rows by one `by` value, day, platform or keyword, and always includes the totals. `range` reads the past UTC days up to today (30d by default). `month` reads one calendar month (YYYY-MM), which is what you match against a bill or a per-client margin. Keyword-days come from the daily run and mention charges from billed matches. So a deleted keyword keeps its charges in the keyword rows (`keyword.removed`), while its mention counts show 0. Each keyword carries the same numbers for the current month as `stats.cost`. `totals.ledgerDebitCents` is what the balance has been debited so far for the period's days. Mentions settle the morning after, so a period ending today is below `totals.totalCents` by the unsettled ones, and a finished month differs only by cumulative rounding. Rows come in pages (`limit`, `offset`, `total`). A workspace can call this 30 times a minute across all its keys and tokens.
- [Get usage and balance](https://docs.rumoro.dev/api/usage/get-usage.mdx): Shows whether tracking is stopped or the balance is low. Also returns the prepaid balance (ledger total, pending mention charges, and the effective balance that decides pausing), daily spend and days left, running and paused keywords, and matches today and over 30 days. Pricing is $0.008 per matched mention, relevant or not, and $5 a month per active keyword, charged daily.
- [Create a view](https://docs.rumoro.dev/api/views/create-view.mdx): Saves a named mention filter. It uses the same fields as GET /v1/mentions, where a list matches any value, a `not` list matches none, and all conditions are joined by AND. `anyOf` adds groups of such conditions, at least one of which must match. An empty filter shows all mentions. Nothing is stored ahead of time, so a view shows whatever matches when you read it.
- [Delete a view](https://docs.rumoro.dev/api/views/delete-view.mdx): Deletes the view. Its mentions are unchanged.
- [Get a view](https://docs.rumoro.dev/api/views/get-view.mdx): Returns one saved view and its filter. Pass its id as `viewId` to list or export the mentions it shows.
- [List views](https://docs.rumoro.dev/api/views/list-views.mdx): Lists the saved views in creation order. A view stores a mention filter under a name. GET /v1/mentions and the exports take its id as `viewId` and return what the view shows.
- [Update a view](https://docs.rumoro.dev/api/views/update-view.mdx): Changes a view's name, description or filter. `filter` sets the full new filter.