Start tracking a keyword: send term (the word or phrase), or query instead, a boolean query as Brand24, Awario or Brandwatch write one ("acme cloud" AND (pricing OR price*) -jobs: quoted phrases, words, AND, OR, NOT or -word, parentheses, a * at a word end; side by side means AND), compiled into term and matching (the first word of every alternative is the term searched everywhere and must be the same in all, so put the brand first; the other words are required, NOT words excluded, exact phrase only); never both, and never query with matching.requiredTerms, requiredMode, requiredGroups, excludedTerms or exactPhrase. A query whose alternatives start with different words (acme OR globex, (acme OR globex) pricing) is refused with query_needs_one_term: add one keyword per term. 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 }.
View input schema
{
"type": "object",
"properties": {
"term": {
"type": "string",
"minLength": 2,
"maxLength": 80,
"description": "The word or phrase to track, case-insensitive. Required unless `query` is sent. 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."
},
"query": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "The keyword as one boolean query instead of term and matching, like \"acme cloud\" AND (pricing OR price*) -jobs ([Keywords](/guides/keywords#write-it-as-a-query)):\n\n- Phrases, words, AND, OR, NOT or -word, parentheses, word-end *\n- Compiled into term and the term rules; never sent with them (400).\n- Each alternative starts with the term; else 400 query_needs_one_term."
},
"kind": {
"type": "string",
"enum": [
"brand",
"competitor",
"topic"
],
"default": "brand",
"description": "brand: your own names. competitor: theirs. topic: the space. Drives share of voice and segments."
},
"platforms": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"enum": [
"bluesky",
"hackernews",
"github",
"stackoverflow",
"devto",
"reddit",
"x",
"youtube",
"news",
"linkedin",
"tiktok",
"instagram",
"facebook"
]
}
},
{
"type": "null"
}
],
"description": "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."
},
"context": {
"anyOf": [
{
"type": "string",
"maxLength": 300,
"description": "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."
},
{
"type": "null"
}
],
"description": "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."
},
"matching": {
"type": "object",
"properties": {
"requiredTerms": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"maxItems": 50,
"description": "The post must ALSO contain these terms, any one of them or all of them per requiredMode. A `*` at the start or the end of an entry is a wildcard (alert* matches alerts and alerting). Empty: no requirement."
},
"requiredMode": {
"type": "string",
"enum": [
"any",
"all"
],
"description": "any: at least one required term must appear. all: every one must."
},
"requiredGroups": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"minItems": 1,
"maxItems": 10
},
"maxItems": 50,
"description": "Combinations: the post must ALSO contain every term of at least one group (an OR of ANDs), on top of requiredTerms, with the same phrase and wildcard rules. See [Keywords](/guides/keywords#several-searches-in-one-keyword)."
},
"excludedTerms": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"maxItems": 50,
"description": "A post containing any of these is dropped. A `*` at the start or the end of an entry is a wildcard (beta.* matches beta.0.1; *bot matches nightlybot)."
},
"excludedAuthors": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"maxItems": 100,
"description": "Posts by these authors are dropped: profile or post links, @handles, u/names, Bluesky DIDs or display names, stored in canonical form like an alert's muted list."
},
"caseSensitive": {
"type": "boolean",
"description": "true: the term must appear in the case it was typed (RAG, never rag). Default false."
},
"exactPhrase": {
"type": "boolean",
"description": "true: only the exact phrase matches (a term sent in double quotes sets it). false: a multi-word keyword also matches its words close together, kept and billed only when scored relevant. See [Keywords](/guides/keywords#the-exact-phrase-only)."
},
"repositories": {
"type": "object",
"properties": {
"events": {
"type": "array",
"items": {
"type": "string",
"enum": [
"new",
"traction",
"stars",
"growth"
]
},
"description": "The repository events this keyword takes (default traction, stars, growth; empty: none). See [GitHub](/platforms/github#repositories).\n\n- traction: under 30 days old, it reached 10 stars.\n- stars: it passed a milestone (100, 250, 500, 1,000 ...).\n- growth: it gained stars fast in a week.\n- new: every repository created; opt in, mostly noise."
},
"minStars": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 1000000
},
{
"type": "null"
}
],
"description": "Only repositories with at least this many stars; null for no minimum."
},
"minWeeklyStars": {
"anyOf": [
{
"type": "integer",
"minimum": 25,
"maximum": 1000000
},
{
"type": "null"
}
],
"description": "Only repositories that gained at least this many stars in the last 7 days, for every event; an unknown week fails. null: growth needs 100 stars and 20% a week, other events nothing."
}
},
"additionalProperties": false,
"description": "GitHub only: each field is replaced when sent, kept when omitted; null clears a minimum."
},
"subreddits": {
"type": "object",
"properties": {
"only": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"maxItems": 50,
"description": "Replaces the keyword's allowlist; [] clears it."
},
"excluded": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"maxItems": 50,
"description": "Replaces the keyword's deny list; [] clears it."
}
},
"additionalProperties": false,
"description": "Reddit only, for this keyword alone: each list is replaced when sent, kept when omitted."
}
},
"additionalProperties": false,
"description": "Omitted fields are untouched; an empty list clears one."
},
"cap": {
"anyOf": [
{
"type": "object",
"properties": {
"mentions": {
"type": "integer",
"minimum": 1,
"maximum": 1000000,
"description": "Charged items allowed per period (see per): matched mentions plus the thread comments delivered under them. Every match counts, relevant or not, the look-back a new keyword gets included, because every match bills."
},
"per": {
"type": "string",
"enum": [
"day",
"week",
"month"
],
"default": "month",
"description": "The period the cap counts in, in UTC: day, week (from Monday) or calendar month (the default). At the cap the keyword stops until the next period starts."
}
},
"required": [
"mentions"
],
"additionalProperties": false,
"description": "A ceiling on what this keyword may be charged for per day, week or month, mentions and comments together. At the cap it stops matching and receiving comments until the next period starts (UTC), or until the cap is raised or removed. It stays unmuted: it keeps its place and its daily keyword charge; pause it to stop that too."
},
{
"type": "null"
}
],
"description": "A mention cap per day, week or month (per, default month); omit or null for none."
},
"comments": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Read the comments under this keyword's relevant mentions. Each comment delivered costs $0.008; comments under three words are dropped, never billed. See [Comments](/guides/comments)."
},
"maxPerPost": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "The newest comments of one thread you receive: the ceiling on what one mention's comments can cost. A comment naming the keyword is a mention only among these."
}
},
"additionalProperties": false,
"description": "Comments under this keyword's mentions; omitted fields are untouched (on create: off, 20 per post)."
},
"display": {
"type": "object",
"properties": {
"languages": {
"type": "object",
"properties": {
"only": {
"type": "array",
"items": {
"type": "string",
"enum": [
"en",
"es",
"de",
"fr",
"pt",
"it",
"nl",
"ca",
"pl",
"tr",
"sv",
"da",
"ru",
"uk",
"ar",
"hi",
"id",
"ja",
"zh",
"ko"
]
},
"maxItems": 60,
"description": "Replaces the list; [] clears it."
},
"excluded": {
"type": "array",
"items": {
"type": "string",
"enum": [
"en",
"es",
"de",
"fr",
"pt",
"it",
"nl",
"ca",
"pl",
"tr",
"sv",
"da",
"ru",
"uk",
"ar",
"hi",
"id",
"ja",
"zh",
"ko"
]
},
"maxItems": 60,
"description": "Replaces the list; [] clears it."
}
},
"additionalProperties": false,
"description": "By the language of the post (ISO 639-1); omitted: untouched."
},
"countries": {
"type": "object",
"properties": {
"only": {
"type": "array",
"items": {
"type": "string",
"enum": [
"us",
"ca",
"mx",
"br",
"ar",
"co",
"cl",
"pe",
"gb",
"ie",
"fr",
"de",
"es",
"pt",
"it",
"nl",
"be",
"ch",
"at",
"se",
"no",
"dk",
"fi",
"pl",
"cz",
"ro",
"gr",
"hu",
"ua",
"ru",
"lt",
"lv",
"ee",
"tr",
"il",
"ae",
"sa",
"eg",
"ng",
"ke",
"za",
"ma",
"in",
"pk",
"bd",
"lk",
"np",
"cn",
"hk",
"tw",
"jp",
"kr",
"sg",
"my",
"id",
"ph",
"vn",
"th",
"au",
"nz"
]
},
"maxItems": 60,
"description": "Replaces the list; [] clears it."
},
"excluded": {
"type": "array",
"items": {
"type": "string",
"enum": [
"us",
"ca",
"mx",
"br",
"ar",
"co",
"cl",
"pe",
"gb",
"ie",
"fr",
"de",
"es",
"pt",
"it",
"nl",
"be",
"ch",
"at",
"se",
"no",
"dk",
"fi",
"pl",
"cz",
"ro",
"gr",
"hu",
"ua",
"ru",
"lt",
"lv",
"ee",
"tr",
"il",
"ae",
"sa",
"eg",
"ng",
"ke",
"za",
"ma",
"in",
"pk",
"bd",
"lk",
"np",
"cn",
"hk",
"tw",
"jp",
"kr",
"sg",
"my",
"id",
"ph",
"vn",
"th",
"au",
"nz"
]
},
"maxItems": 60,
"description": "Replaces the list; [] clears it."
}
},
"additionalProperties": false,
"description": "By where the author is (ISO 3166-1 alpha-2); omitted: untouched."
}
},
"additionalProperties": false,
"description": "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": {
"type": "string",
"minLength": 1,
"description": "The group to track it in (grp_...); omit for the workspace's default group. A term may be tracked once per group."
},
"reviewSources": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "The review page's link: an App Store or Google Play app (https://apps.apple.com/us/app/notion/id1232780281, https://play.google.com/store/apps/details?id=notion.id), a Trustpilot page (https://www.trustpilot.com/review/notion.so) or a Google Maps place (its full link, or a maps.app.goo.gl share link). Or give platform and id."
},
"platform": {
"type": "string",
"enum": [
"appstore",
"googleplay",
"trustpilot",
"googlemaps"
],
"description": "appstore (Apple App Store), googleplay (Google Play), trustpilot (a company's Trustpilot page) or googlemaps (a place's Google reviews)."
},
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "The id on the platform: the digits after \"id\" on the App Store, the package name on Google Play, the company's domain on Trustpilot (notion.so), a Place ID (ChIJ...) on Google Maps."
},
"countries": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Za-z]{2}$"
},
"minItems": 1,
"maxItems": 20,
"description": "App Store and Google Play storefronts to read, as two-letter codes; default the link's, else us. Each adds a daily poll; a review seen in two is one mention. Trustpilot and Google Maps take none."
},
"language": {
"type": "string",
"minLength": 2,
"maxLength": 10,
"description": "Google Play only: the language of the reviews to read (en, es, de, pt-BR); Google Play answers one language at a time. Default: the link's hl, else en."
}
},
"additionalProperties": false,
"description": "A review page whose reviews become this keyword's mentions: its link, or the platform and the id."
},
"maxItems": 10,
"description": "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)."
},
"feeds": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": "string",
"minLength": 4,
"maxLength": 500,
"description": "A feed's address (https://forum.example.com/posts.rss), or a page's (https://forum.example.com): the feed the page advertises is used."
}
},
"required": [
"url"
],
"additionalProperties": false,
"description": "One feed to read."
},
"maxItems": 20,
"description": "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)."
},
"readsWorkspaceFeeds": {
"type": "boolean",
"description": "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."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"pattern": "^[\\x21-\\x7e]+$",
"description": "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."
}
},
"additionalProperties": false
}