Estimate a keyword or a change
keyword_estimatePrice a new keyword (no id, the arguments of keyword_create) or a change to one (an id, the arguments of keyword_update) without writing anything. valid=false carries the refusal the write would give: the status, the code and the sentence naming the fix. valid=true carries monthlyCredits in total, per Source and per search, firstScanCredits when backfill is true (the most the first scan can cost, see backfill), the plan allowance and the credits left, and for a change the monthly difference and resetSearches, the searches it would start over. A new keyword also carries volume when it names a free Source (Reddit, Bluesky, Hacker News, GitHub, Stack Overflow, Mastodon, Lemmy, RSS): the estimated mentions a month on the Sources in measuredOn, and a bucket from none to over_10k, free and never charged. Show the person monthlyCredits before any write, then pass estimateToken to that write with the same arguments. What each Source needs in a search is in the description of searches[].overrides. A topic keyword (subjectRole topic) sent without globalCriteria.match is created with match word, the phrase as written; send match contains to widen it, or platform for the platform's own matching. For a topic, also send sentimentEnabled true and an aiStep with a boolean problem_fit field (true only when the author has the problem themselves): the opportunity filter of list_mentions reads it. Costs 0 credits and writes nothing. Returns what the write would cost a month, computed by the functions that charge it, and the estimateToken the write requires.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Absent: price a new keyword, with the arguments of keyword_create. A keyword id: price a change, with the arguments of keyword_update. | |
| name | No | ||
| color | No | The keyword colour in the dashboard. Left out on create, an unused one is picked. | |
| rules | No | Replaces the list. Copy the shape from get_keyword on an existing keyword. | |
| aiStep | No | Your own question asked of every mention, with the fields to fill: {"instruction": one or two sentences, 800 characters at most, "schema": 1 to 12 flat fields, each {"type": "string" | "number" | "boolean" | "enum", "description", "values" for an enum, "maxLength" for a string}}, no nesting and no arrays. The answer arrives on each event as analysis. Costs 1 credit per 25 items, on top of the check rate. Delivery waits up to 120s for it; on timeout the event is still delivered, with the answer null and a status saying why. null removes it. | |
| sources | No | The Sources this keyword polls, one entry each; a single entry is a keyword that polls one Source. Each enabled search is one check at its rate. What each Source needs is in the description of searches[].overrides. | |
| aiPreset | No | ||
| aiPrompt | No | ||
| backfill | No | true runs a first scan right away, so the keyword is not empty on day one. What it finds fires no webhook, since a first scan is context and not news, and comes back marked seeded. A first scan is one search per enabled Source at that Source's check rate, except where a Source is billed per result: on X it is 5 credits plus 3 per result returned, at most 65 credits for its page of 20. So a first scan that includes such a Source is quoted at its ceiling: say "up to". Needs the nephia:spend permission. AI answers never backfills. | |
| channels | No | Replaces the delivery channels attached to the keyword. | |
| schedule | No | An activation window with ISO instants. null keeps the keyword always on. | |
| aiEnabled | No | Sort mentions into buckets. | |
| muteRules | No | Replaces the list. A plain string mutes that word. | |
| spikeAlert | No | The alert a new keyword starts with. null starts with none. Free. | |
| vipAuthors | No | Replaces the list. A plain string is a handle. | |
| webhookUrl | No | A publicly reachable HTTPS endpoint the person controls: new mentions are POSTed there. Never invent this URL, ask the person for it. Left out, the keyword records what it catches without pushing it, and you read it with list_mentions, get_keyword_results or get_keyword_events. null removes the webhook. | |
| subjectRole | No | What the keyword is about: your own brand, a competitor's, or a topic. A new topic without globalCriteria.match is created with match word. | |
| webhookMode | No | all delivers every new mention; rules delivers only what a rule routes. | |
| globalCriteria | No | The criteria every search inherits: market (required, e.g. "us") and query or terms. AI answers reads no search text, so a keyword of prompts only still names a market. | |
| coBrandsEnabled | No | AI answers only: also read each answer for the other brands it names, charged per answer on top of the run. | |
| relevanceContext | No | One sentence the AI reading uses to judge relevance, such as "Acme is a cloud storage company, not the cartoon." null clears it. | |
| sentimentEnabled | No | Read every mention for sentiment and intent. | |
| refreshIntervalSeconds | No | Default seconds between checks, for every Source without its own interval. The plan and each Source set a floor; the estimate names the band when a value is outside it. |