OverviewPlatformsAPI Reference
Keywords

Get a keyword

GET
/v1/keywords/{id}

Authorization

AuthorizationBearer <token>

API key minted via POST /v1/api-keys (format mk_live_...)

In: header

Path Parameters

idstring

Keyword id (kw_...).

Length1 <= length

Response Body

application/json

application/json

application/json

curl -X GET "https://api.mentio.dev/v1/keywords/kw_abc123"
{
  "id": "string",
  "term": "string",
  "kind": "brand",
  "muted": true,
  "pausedForBalance": true,
  "pausedForNoise": true,
  "pausedForCap": true,
  "cap": {
    "mentions": 1,
    "per": "day",
    "used": 0,
    "welcome": true,
    "own": 0,
    "ownPer": "day",
    "resumesAt": "string"
  },
  "comments": {
    "enabled": true,
    "maxPerPost": 1
  },
  "display": {
    "languages": {
      "only": [
        "en"
      ],
      "excluded": [
        "en"
      ]
    },
    "countries": {
      "only": [
        "us"
      ],
      "excluded": [
        "us"
      ]
    }
  },
  "group": {
    "id": "string",
    "name": "string",
    "externalId": "string",
    "isDefault": true
  },
  "platforms": [
    "bluesky"
  ],
  "feeds": [
    {
      "url": "string",
      "title": "string",
      "connectedAt": "string"
    }
  ],
  "readsWorkspaceFeeds": true,
  "reviewSources": [
    {
      "platform": "appstore",
      "id": "string",
      "url": "string",
      "countries": [
        "string"
      ],
      "language": "string",
      "connectedAt": "string"
    }
  ],
  "context": "string",
  "matching": {
    "requiredTerms": [
      "string"
    ],
    "requiredMode": "any",
    "requiredGroups": [
      [
        "string"
      ]
    ],
    "excludedTerms": [
      "string"
    ],
    "excludedAuthors": [
      "string"
    ],
    "caseSensitive": true,
    "exactPhrase": true,
    "subreddits": {
      "only": [
        "string"
      ],
      "excluded": [
        "string"
      ]
    },
    "repositories": {
      "events": [
        "new"
      ],
      "minStars": 1000000,
      "minWeeklyStars": 25
    }
  },
  "stats": {
    "mentions": 0,
    "relevant": 0,
    "last7d": 0,
    "thisMonth": 0,
    "lastMentionAt": "string",
    "feedback": {
      "relevant": 0,
      "notRelevant": 0
    },
    "noise": {
      "scored": 0,
      "relevant": 0,
      "noisy": true
    },
    "health": "healthy",
    "cost": {
      "keywordDays": 0,
      "keywordCents": 0,
      "billableMentions": 0,
      "mentionCents": 0,
      "billableComments": 0,
      "commentCents": 0,
      "totalCents": 0
    }
  },
  "polling": [
    {
      "platform": "bluesky",
      "lastPolledAt": "string",
      "emptyPolls": 0
    }
  ],
  "createdAt": "string"
}
{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "requestId": "string",
    "retryAfterSeconds": 0
  }
}
{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "requestId": "string",
    "retryAfterSeconds": 0
  }
}

Get a keyword's health GET

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.

List keywords GET

The keywords of the workspace with their match stats and poll health. Without parameters: every keyword, newest first. `q` searches the term and the context; `kind`, `status` and `platform` narrow the list; `sort` orders it; `limit` and `offset` page it. `total` counts the keywords that matched before paging.