Keywords

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.

get/v1/keywords/{id}/health

Request

  • Base URL: https://api.mentio.dev
  • URL: https://api.mentio.dev/v1/keywords/{id}/health
  • Auth: HTTP bearer

Path parameters

idstring required

Keyword id (kw_...).

Example:kw_abc123

Query parameters

range'7d' | '30d' | '90d'

Trailing window of UTC days ending today, by match time: 7d, 30d, 90d (default 30d).

aiboolean

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

The keyword's health report

status'healthy' | 'noisy' | 'quiet' | 'capped' | 'paused' | 'new' required

healthy: nothing to fix. noisy: 20 or more scored matches in the window and under 30% of them relevant. quiet: 7 days or older with no relevant match in the window. capped: at its monthly mention cap. paused: muted (by you, the wallet or the noise brake). new: under 7 days old and not noisy yet, or changed in the last 7 days with under 20 scored matches since the change. When the keyword's matching rules, platforms or context changed (or it was unmuted) inside the window, the status reads only the matches since then (stats.judgedSince).

reasonsstring[] required

Why, in plain words; the first line explains the status.

generatedAtstring required

When the report was computed; it is cached for 5 minutes, and a change to the keyword starts a fresh one.

Changes

No recorded changes to this operation across all 1 revision of this API.