---
title: "Choosing keywords"
description: "How a keyword finds posts, how to pick terms that bring the conversations you want, how to narrow a noisy one, and what it costs."
canonical: https://docs.rumoro.dev/guides/keywords
markdown: https://docs.rumoro.dev/guides/keywords.mdx
---

# Choosing keywords

How a keyword finds posts, how to pick terms that bring the conversations you want, how to narrow a noisy one, and what it costs.

A keyword is the word or phrase Rumoro looks for. A good one fills your feed with posts about you; a sentence or a common word fills it with noise or nothing at all. This page explains how matching works and how to choose terms that do.

## How a keyword matches

A term matches as a whole phrase, ignoring case, wherever it appears in a post's title or text. `acme cloud` finds "We moved to Acme Cloud last year" but not "Acme's cloud offering". Every post that matches is stored, scored by the classifier and billed, relevant or not. Scoring decides what reaches your [alerts](/alerts); it doesn't decide what you pay for.

On Hacker News, X, Reddit and the other platforms the term is searched; on [review pages](/platforms/reviews) every review counts; in [RSS feeds](/platforms/rss) an item counts when it holds the term.

## Choose terms people actually write

- **Your product's name as people type it.** `posthog`, not `PostHog Inc.`. Add the spellings people really use as separate keywords.
- **Short phrases, not sentences.** `fundraising agency` finds people talking about one; `looking for a fundraising agency` almost never matches anything.
- **Competitors as their own keywords**, with `kind: "competitor"`, so [share of voice](/api/analytics/get-share-of-voice) can compare you.
- **Topics you want to join**, with `kind: "topic"`: `vector database`, `cold email deliverability`.

A new keyword starts with the 10 newest matching posts of the last 30 days on each platform that supports it, so you see within a minute whether the term finds what you expect.

## Narrow a broad keyword

If your name is also a common word (Arc, Basil, Mercury), the keyword's `matching` rules remove the wrong posts before they are stored, so you are never billed for them:

- `requiredTerms`: the post must also contain one of them (`requiredMode: "any"`) or all of them (`"all"`), such as `browser` for Arc.
- `excludedTerms`: a post with any of them is dropped. `*` at the start or end is a wildcard: `hiring*`, `*bot`.
- `excludedAuthors`: people whose posts you never want for this keyword.
- `caseSensitive`: the term must appear as typed, for acronyms such as `RAG`.

```bash tab="curl"
curl -X PATCH https://api.rumoro.dev/v1/keywords/kw_... \
  -H "Authorization: Bearer $RUMORO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "matching": { "requiredTerms": ["browser", "tabs"], "excludedTerms": ["geometry", "welding"] } }'
```

```ts tab="TypeScript"
await rumoro.updateKeyword({ path: { id: 'kw_...' }, body: { matching: { requiredTerms: ['browser', 'tabs'], excludedTerms: ['geometry', 'welding'] } } });
```

```python tab="Python"
rumoro.keywords.update("kw_...", matching={"requiredTerms": ["browser", "tabs"], "excludedTerms": ["geometry", "welding"]})
```

Rules for every keyword at once (excluded terms, authors, GitHub repositories, subreddits) live in the [workspace filters](/api/filters/update-filters). [Keyword health](/guides/keyword-health) shows where a keyword's noise comes from and suggests rules.

## Tell the classifier what you mean

`context` is one sentence the classifier reads for this keyword only: "Arc is our browser; ignore the geometry word." It changes the relevance score, not what is stored. Use rules to keep posts out and context to judge the ones that remain.

## Rename or duplicate a keyword

**Rename** a keyword to fix a typo or sharpen it: change its term in the keyword's settings, or send `term` on [`PATCH /v1/keywords/{id}`](/api/keywords/update-keyword). It keeps its id, its settings and the mentions it already found. The new term is tracked from the moment you rename it, with no look-back and no extra charge. A group tracks a term once, so renaming to a term the group already has is a `409`.

**Duplicate** a keyword to track another term with the same settings: the Duplicate button in its settings, or [`POST /v1/keywords/{id}/duplicate`](/api/keywords/duplicate-keyword) with the new `term`.

```ts tab="TypeScript"
const { data: copy } = await rumoro.duplicateKeyword({ path: { id: 'kw_...' }, body: { term: 'acme cloud' } });
```

```python tab="Python"
copy = rumoro.keywords.duplicate("kw_...", term="acme cloud")
```

```bash tab="curl"
curl -X POST https://api.rumoro.dev/v1/keywords/kw_.../duplicate \
  -H "Authorization: Bearer $RUMORO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "term": "acme cloud" }'
```

The copy gets the same kind, platforms, context, matching rules, cap and [comments](/guides/comments) setting. Its review pages and feeds are copied only when you ask with `include: ["reviewSources", "feeds"]`, because two keywords on one page or feed collect, and bill, every review or item twice. The copy is a new keyword in every other way: it starts active, costs $5 a month, and brings its own last 30 days. To keep the same term, put the copy in another [group](/guides/groups) with `groupId`. In MCP the tool is `duplicate_keyword`; on the command line, `rumoro keywords:duplicate`.

## What you pay for

- **The keyword:** $5 a month, taken from your balance day by day while it is active. A paused keyword costs nothing.
- **Each matched mention:** $0.008, relevant or not, which is why narrowing a broad keyword saves money.
- **Comments,** if you switch them on: $0.008 each. See [Comments](/guides/comments).

A [cap](/billing#capping-a-keywords-mentions) puts a ceiling on what one keyword can spend on mentions and comments in a month. See [Billing](/billing) for the welcome credit and the ledger.