---
title: "Get a keyword's health"
description: "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."
canonical: https://docs.mentio.dev/api/keywords/get-keyword-health
markdown: https://docs.mentio.dev/api/keywords/get-keyword-health.mdx
---

# Get a keyword's health

`GET /v1/keywords/{id}/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.

## Parameters

- `id` (path, required): Keyword id (kw_...).
- `range` (query): Trailing window of UTC days ending today, by match time: 7d, 30d, 90d (default 30d).
- `ai` (query): 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.

## Responses

- 200: The keyword's health report
- 400: Invalid query parameters
- 401: Missing or invalid API key
- 404: Keyword not found
- 429: More than 30 health reads this minute (rate_limited)

Full schemas: https://api.mentio.dev/v1/openapi.json. Conventions: https://docs.mentio.dev/conventions.mdx