Agentic Platform
Documentation API reference Tools Skills

Tools

Keywords Clustering

keywords_clustering Keywords

Cluster keywords into groups.

This tool groups keywords provided by @KeywordsSuggestions or @KeywordsSuggestionsGoogleAdsPlanner into thematic clusters based on user intent and behavior. The clustering reveals content opportunities by combining related terms, considering search volume, competition, and commercial intent. These clusters inform content strategy by highlighting topic hierarchies, gaps, and potential site structure improvements. Each cluster includes a relevance assessment to guide content prioritization.

Playground

Your organization, project and token stay in this browser's local storage and are sent straight to the API — this page never sees them.

POST
item
tool_origin required Tool origin to get keywords from
language Target language for clusters
keywords required List of keywords to cluster
config
location_id Location ID (optional)
location_request Location request (ex: Paris, FR), will translate to location ID
country_code ISO3166 country code (ex: GB)
lang_code BCP47 language code (ex: "en", "en-GB")
device Device to use for search (optional - defaults to mobile)

Billing

Fixed cost per item requested, plus whichever keyword source you name in tool_origin -- only one of the two is ever called, and keyword planner data costs far more than keyword research. On top of that, one model call groups the keywords; it sees at most twenty of them, so that part does not grow with the size of the source.

These usage SKUs can be charged on a call, including SKUs from tools this one may call.

SKU Credits Description Used by
Tool call 1 per request Charged once per successful item, on top of any usage below.
  • This tool
GPT-4o (standard), input 2,500 per million tokens Tokens the model reads from the prompt you send.
  • This tool
GPT-4o (standard), output 10,000 per million tokens Tokens the model writes in its answer.
  • This tool
GPT-4o (standard), read from cache 1,250 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.
  • This tool
Keyword planner data 50 per request Search volume and related keywords from advertising keyword-planner data. One request covers every seed you pass, and it is by a wide margin the dearest keyword source Botify offers.
Keyword research 10 per request Keyword ideas and their metrics for one seed. Billed twice over: once for asking, and again for each keyword that comes back.
Keyword research, per keyword returned 1 per 10 keyword returned Each keyword a research request hands back. A narrow seed costs less than a broad one.

Schemas

item is what you send, config how the tool behaves, and the response is what you get back.

Item

object
Properties
tool_origin string required

Tool origin to get keywords from

Values: keywords_suggestions keywords_suggestions_google_ads_planner

language string

Target language for clusters

Default: "en"

keywords array required

List of keywords to cluster

max items 20

Example
{
  "tool_origin": "keywords_suggestions",
  "language": "en",
  "keywords": [
    "string"
  ]
}

Configuration

object
Properties
location_id integer | null

Location ID (optional)

Default: null

location_request string | null

Location request (ex: Paris, FR), will translate to location ID

Default: null

country_code string | null

ISO3166 country code (ex: GB)

Default: null

lang_code string | null

BCP47 language code (ex: "en", "en-GB")

Default: null

device string

Device to use for search (optional - defaults to mobile)

Values: mobile desktop

Default: "mobile"

Example
{
  "location_id": null,
  "location_request": null,
  "country_code": null,
  "lang_code": null,
  "device": "mobile"
}

Response

object
Properties
clusters array required

List of keyword clusters

Items: KeywordsCluster

website_description_used_for_clustering string required

The website description that was used to assess cluster relevance

website_description_used_for_clustering__notes string required

Notes about the website description used for clustering

Example
{
  "clusters": [
    {
      "name": "string",
      "main_keyword": "string",
      "keywords": [
        "string"
      ],
      "rationale": "string",
      "relevant_for_website": true
    }
  ],
  "website_description_used_for_clustering": "string",
  "website_description_used_for_clustering__notes": "string"
}

Type Definitions

1 type

These are the available sub-object types that can be used in the properties above.

KeywordsCluster object
#
name string required

Name of the keywords cluster

main_keyword string required

The main keyword representing the cluster

keywords array required

List of keywords belonging to this cluster

rationale string required

Explanation of why these keywords are grouped together

relevant_for_website boolean required

Whether this cluster is relevant for the website based on its description

Endpoints

POST http://agents.botify.com/{organization}/{project}/keywords_clustering/process
POST http://agents.botify.com/{organization}/{project}/keywords_clustering/batch_process
POST http://agents.botify.com/{organization}/{project}/keywords_clustering/async_process
POST http://agents.botify.com/{organization}/{project}/keywords_clustering/async_batch_process

See running a long job in the background for the polling flow.

cURL

curl -X POST "http://agents.botify.com/{organization}/{project}/keywords_clustering/process" \
  -H "Authorization: Bearer $BOTIFY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "item": {
    "tool_origin": "<tool_origin>",
    "keywords": []
  }
}'

Raw metadata