Add keyword
add_keywordStart tracking a keyword. kind is "brand" (default), "competitor" or "topic". platforms optionally restricts it to some platforms (default: every platform). New mentions containing the term will be matched, classified and delivered. A multi-word term also matches a post holding its words close together (any order, plurals and spellings like non-profit/nonprofit); such a post is kept and billed only when the classifier scores it relevant. Wrap the term in double quotes, or set matching.exactPhrase, for the exact phrase only. Prefer short terms people actually write ("fundraising agency") over sentences ("looking for a fundraising agency"). For a common word, narrow it with matching (requiredTerms with requiredMode any|all, requiredGroups: combinations where the post must hold every term of at least one, as [["weather","alert*"],["tsunami"]], so one keyword replaces a search per line, excludedTerms, a * wildcard at an end of any rule term, excludedAuthors, caseSensitive, exactPhrase, subreddits: { only, excluded } to keep its Reddit posts to some subreddits or out of some): a post the rules reject is never stored or billed. context is one sentence the classifier reads for this keyword only ("Arc is our browser; ignore the geometry word"). cap ({ mentions: N, per: "day" | "week" | "month" }, per defaults to month) is a ceiling on its matched mentions per UTC day, week (from Monday) or month: at the cap it stops matching until the next period starts or until the cap is raised, while its daily keyword charge continues. A daily cap keeps mentions coming every day with a fixed ceiling on spend (N × $0.008 a day at most, plus the keyword). groupId puts it in a keyword group (list_groups; default: the workspace's default group); a term may be tracked once per group, so two groups may track the same term as two keywords. reviewSources collects reviews: pass each page's link (url: an App Store or Google Play app, a Trustpilot page, a Google Maps place or its maps.app.goo.gl share link) or platform (appstore|googleplay|trustpilot|googlemaps) and id; the app stores also take countries (two-letter codes, default us) and Google Play a language (default en). Every review of the page becomes a mention of this keyword, polled daily, and the last 30 days (newest 100) come in free at once. feeds reads RSS or Atom feeds: pass each as { url }, a feed's URL or a page's (a forum, a community, a blog) whose advertised feed is used; a URL with no feed is refused. An item of a feed is a mention of this keyword when it holds the term, polled every hour, and the newest 10 matching items of the last 30 days come in at once (billed like any mention). platforms: [] makes a reviews-only or feeds-only keyword. comments ({ enabled: true, maxPerPost: N }, off by default) reads the comments under its relevant mentions from 30 minutes after each post, as long as its platform's conversations last (a day on Reddit, Hacker News and Bluesky, a week on GitHub, Stack Overflow and DEV, a month on YouTube), $0.008 per comment delivered (comments of fewer than three words are skipped), at most maxPerPost (default 20) per mention; list them with list_mention_comments. display ({ languages: { only, excluded }, countries: { only, excluded } }, lowercase ISO 639-1 and ISO 3166-1 alpha-2 codes) chooses which of its mentions you see by the post's language and the author's country: a hidden mention is still matched, classified and billed, but stays out of search_mentions, exports, alerts and digests; a post whose language or country nobody could tell is always shown. On GitHub a keyword also gets events about repositories naming it; matching.repositories chooses them: events (traction: a repository under 30 days old reached 10 stars; stars: a star milestone from 100 up; growth: fast growth in a week; new: every repository created, even with no stars, off by default), minStars and minWeeklyStars (stars gained in 7 days, 25 or more). An event outside the rule is dropped before it is stored, so it is never billed: "repositories about X with 200+ stars gaining 100 a week" is { events: ["stars","growth"], minStars: 200, minWeeklyStars: 100 }.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"term": "<term>"
},
"name": "add_keyword"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | A mention cap per day, week or month (per, default month); omit or null for none. | |
| kind | No | brand: your own names. competitor: theirs. topic: the space. Drives share of voice and segments. | brand |
| term | Yes | The word or phrase to track, case-insensitive. A multi-word term matches as the phrase or as its words close together (see matching.exactPhrase); wrap it in double quotes for the exact phrase only. | |
| feeds | No | RSS or Atom feeds only this keyword reads: a feed's URL, or a page that advertises one (else a 400). Read hourly; an item holding the term is a mention. See [RSS](/platforms/rss#a-keywords-own-feeds). | |
| context | No | A sentence the classifier reads for this keyword only, on top of the company profile or group description: what the term means here, what to ignore. "Arc is our browser; ignore the geometry word." Null clears it. | |
| display | No | Which of this keyword's mentions you see, by language and country; each list is replaced when sent, kept when omitted. Hidden mentions are still billed. | |
| groupId | No | The group to track it in (grp_...); omit for the workspace's default group. A term may be tracked once per group. | |
| comments | No | Comments under this keyword's mentions; omitted fields are untouched (on create: off, 20 per post). | |
| matching | No | Omitted fields are untouched; an empty list clears one. | |
| platforms | No | Platforms to search the term on; omit or null for every platform. [] searches it nowhere: a keyword that only collects reviews or reads feeds, which then needs reviewSources or feeds. | |
| reviewSources | No | Review pages this keyword collects (app store apps, Trustpilot pages, Google Maps places): every new review is a mention, whatever it says. Polled daily; a newly connected page brings 30 days back, free. See [Reviews](/platforms/reviews). | |
| idempotencyKey | No | Optional. A unique value (a UUID) for this call: 1 to 255 visible ASCII characters, no spaces. Calling again with the same key and the same input within 24 hours returns the first result instead of doing it twice. | |
| readsWorkspaceFeeds | No | Whether the keyword also reads the workspace's feeds (GET /v1/feeds); default true. A new keyword reading them gets the look-back of the 8 most recently connected. |