Check a keyword's health
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.
Authorization
bearerAuth An API key from POST /v1/api-keys. Keys start with ref_.
In: header
Path Parameters
The keyword's id (kw_...).
1 <= lengthQuery Parameters
How many UTC days back from today to read, by match time. One of 7d, 30d or 90d, 30d by default.
Value in
- "7d"
- "30d"
- "90d"
true also asks a language model to rewrite the context. The answer is cached for a day per keyword and window, with at most 20 model calls an hour per workspace. With the default false, all suggestions come from the rules only.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/keywords/kw_abc123/health"{ "keyword": { "id": "string", "term": "string", "group": { "id": "string", "name": "string", "externalId": "string", "isDefault": true } }, "window": { "from": "string", "to": "string", "days": 0 }, "status": "healthy", "reasons": [ "string" ], "stats": { "matches": 0, "relevant": 0, "filtered": 0, "unscored": 0, "noiseShare": 0, "workspaceShare": 0, "judgedSince": "string", "byPlatform": [ { "platform": "bluesky", "matches": 0, "relevant": 0, "filtered": 0, "noiseShare": 0 } ], "weekly": [ { "from": "string", "matches": 0, "relevant": 0 } ], "cost": { "keywordDays": 0, "keywordCents": 0, "billableMentions": 0, "mentionCents": 0, "totalCents": 0 } }, "sample": { "noise": 0, "relevant": 0 }, "noiseTerms": [ { "term": "string", "noisePosts": 0, "relevantPosts": 0, "lift": 0 } ], "noiseAuthors": [ { "name": "string", "entry": "string", "noisePosts": 0 } ], "suggestions": [ { "type": "excluded_terms", "values": [ "string" ], "why": "string", "patch": { "kind": "brand", "muted": true, "platforms": [ "bluesky" ], "context": "string", "matching": { "requiredTerms": [ "string" ], "requiredMode": "any", "excludedTerms": [ "string" ], "excludedAuthors": [ "string" ], "caseSensitive": true }, "cap": { "mentions": 1 }, "groupId": "string", "reviewSources": [ { "url": "string", "platform": "appstore", "id": "string", "countries": [ "string" ], "language": "string" } ] }, "effect": { "noiseRemoved": 0, "relevantRemoved": 0, "centsSaved": 0, "sample": { "noiseRemoved": 0, "noise": 0, "relevantRemoved": 0, "relevant": 0 }, "exact": true }, "source": "rules" } ], "ai": { "requested": true, "status": "off" }, "generatedAt": "string"}