Get a keyword's health
Whether the keyword earns what it costs over a trailing window (`range`, default 30d): a status (healthy, noisy, quiet, capped, paused, new) with the reasons in plain words, its numbers by platform and week, what it cost, the words and authors its noise is made of, and suggestions. Each suggestion carries a `patch` to send to PATCH /v1/keywords/{id} as is, and the effect it would have had, measured by running the matcher's own rules over the window's posts. `ai=true` adds a context rewritten by a language model (cached a day, at most 20 model calls an hour per workspace). Read only and never billed; the report is cached for 5 minutes, and a change to the keyword starts a fresh one. At most 30 reads a minute per workspace.
API key minted via POST /v1/api-keys (format mk_live_...)
In: header
Path Parameters
Keyword id (kw_...).
1 <= lengthQuery Parameters
Trailing window of UTC days ending today, by match time: 7d, 30d, 90d (default 30d).
"7d" | "30d" | "90d"true: also ask a language model for a rewritten context (cached a day per keyword and window, at most 20 model calls an hour per workspace). Default false: every suggestion comes from the rules alone.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.mentio.dev/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": 1,
"workspaceShare": 1,
"judgedSince": "string",
"byPlatform": [
{
"platform": "bluesky",
"matches": 0,
"relevant": 0,
"filtered": 0,
"noiseShare": 1
}
],
"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"
}{
"error": {
"code": "unauthorized",
"message": "string",
"requestId": "string",
"retryAfterSeconds": 0
}
}{
"error": {
"code": "unauthorized",
"message": "string",
"requestId": "string",
"retryAfterSeconds": 0
}
}{
"error": {
"code": "unauthorized",
"message": "string",
"requestId": "string",
"retryAfterSeconds": 0
}
}{
"error": {
"code": "unauthorized",
"message": "string",
"requestId": "string",
"retryAfterSeconds": 0
}
}