Skip to main content
GET /v1/keywords/expand
Returns the closest known keywords to the seed by cosine similarity in a 1536-dim embedding space (text-embedding-3-small). Unlike Apple’s autocomplete, semantic expansion catches keywords that share meaning but not letters — "to-do" finds "task list", "focus timer" finds "pomodoro". Each result also carries the keyword’s volumeScore and rankVolatility so you can rank by “high volume + similar to seed” without a second roundtrip.

​
Query Parameters

NameTypeRequiredDefaultDescription
keywordstringYes—The seed keyword to expand
countrystringNousISO 3166-1 alpha-2 storefront
limitnumberNo25Max related keywords returned, 1–100

​
Response

{
  "ok": true,
  "data": {
    "seed": "ai chat",
    "country": "us",
    "total": 8,
    "cachedSeed": true,
    "related": [
      { "keyword": "ai assistant",   "similarity": 0.871, "volumeScore": 64, "rankVolatility": 21.3 },
      { "keyword": "chatbot",        "similarity": 0.842, "volumeScore": 58, "rankVolatility": 14.8 },
      { "keyword": "ai conversation","similarity": 0.811, "volumeScore": 41, "rankVolatility": 9.0 }
    ]
  }
}
cachedSeed is true when the seed already had an embedding stored (no OpenAI call needed). false means the seed was just embedded for the first time — subsequent calls within ~30 days will be cached. The volumeScore and rankVolatility fields can be null if the keyword has not yet been enriched. The similarity floor is 0.55, so very weak matches are not returned.

​
Credit Cost

4 credits per request.

​
Use Cases

  • “More like this” suggestions on a keyword detail page.
  • Brainstorm support: type a candidate, see semantically-adjacent search terms you would have missed.
  • Build a personalised tracking list by expanding a small set of seed keywords.