OverviewPlatformsAPI Reference
Keywords

Get a keyword

Returns one keyword with its matching rules, review pages, this month's cost and the polling status on each platform.

GET
/v1/keywords/{id}

Authorization

bearerAuth
AuthorizationBearer <token>

An API key from POST /v1/api-keys. Keys start with ref_.

In: header

Path Parameters

id*string

The keyword's id (kw_...).

Length1 <= length

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/v1/keywords/kw_abc123"
{  "id": "string",  "term": "string",  "kind": "brand",  "muted": true,  "pausedForBalance": true,  "pausedForNoise": true,  "pausedForCap": true,  "cap": {    "mentions": 1,    "welcome": true,    "own": 0  },  "group": {    "id": "string",    "name": "string",    "externalId": "string",    "isDefault": true  },  "platforms": [    "bluesky"  ],  "reviewSources": [    {      "platform": "appstore",      "id": "string",      "url": "string",      "countries": [        "string"      ],      "language": "string",      "connectedAt": "string"    }  ],  "context": "string",  "matching": {    "requiredTerms": [      "string"    ],    "requiredMode": "any",    "excludedTerms": [      "string"    ],    "excludedAuthors": [      "string"    ],    "caseSensitive": true  },  "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,      "totalCents": 0    }  },  "polling": [    {      "platform": "bluesky",      "lastPolledAt": "string",      "emptyPolls": 0    }  ],  "createdAt": "string"}
Was this page helpful?

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.

List keywords

Returns the workspace's keywords with their match counts and polling status. With no parameters you get all keywords, latest first. `q` searches the term and context. `kind`, `status` and `platform` filter the list, `sort` orders it, and `limit` and `offset` page through it. `total` is the number of matching keywords before paging.