# GET /v1/projects/:projectId/keywords (/docs/api/reference/keywords/list-keywords)



<Endpoint method="GET" path="/v1/projects/:projectId/keywords" 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`](/docs/api/reference/keywords/refresh-keywords) to populate it.

## Response [#response]

<Response status="200" description="OK">
  ```json
  {
    "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"
  }
  ```
</Response>

| 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 [#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.   |

## See also [#see-also]

* [Refresh keywords](/docs/api/reference/keywords/refresh-keywords)
* [Source recommendations](/docs/api/reference/content/source-recommendations) — feed any of these hashtags as `?keyword=…`