GET /v1/projects/:projectId/keywords

GET/v1/projects/:projectId/keywords

stable

Auth: Bearer
Scope: projects:read

Returns hashtags sorted by score desc (tie-broken on viewCount desc). Empty array + refreshedAt: null when the bank has never been generated — call POST /keywords/refresh to populate it.

Response

200OK

{
  "projectId": "prj_01HZ...",
  "hashtags": [
    {
      "hashtag": "morningroutine",
      "phrase": "morning routine",
      "score": 92,
      "viewCount": 184201000,
      "useCount": 412000
    },
    {
      "hashtag": "coffeehack",
      "phrase": "coffee hack",
      "score": 88,
      "viewCount": 12000000,
      "useCount": 89000
    }
  ],
  "refreshedAt": "2026-05-11T19:08:44.317Z"
}

Field	Notes
`hashtag`	Bare hashtag — no `#` prefix. Pass directly as `?keyword=` on source-recommendations.
`phrase`	The free-text phrase the keyword was extracted from. Useful for UI labels.
`score`	0–100. ≥ 70 is the curation floor — anything below was filtered out.
`viewCount`	Lifetime view count for the hashtag on TikTok.
`useCount`	Post count using the hashtag on TikTok.
`refreshedAt`	When the bank was last refreshed (`updated_at` on `project_keywords`). Null when the bank has never been generated.

Errors

Status	Code	When
401	`UNAUTHENTICATED`	Missing or invalid key.
403	`FORBIDDEN_SCOPE`	Key lacks `projects:read`.
404	`NOT_FOUND`	Project not in this org.

GET /v1/projects/:projectId/keywords

Response

Errors

See also

On this page