Find top searches
find_top_searchesThe most searched keywords in a market, highest monthly volume first, narrowed by text they contain, a least volume and a highest keyword difficulty, each with its volume, CPC, difficulty and search intent. Estimated price: up to $0.05, one market data request for up to 100 keywords, billed by the rows returned. The same filters and market saved within a day are read free, and they open free on the Top searches page. Each call may spend up to the workspace's agent spend limit ($2.00 unless changed in Settings) without asking: it holds at most its estimate plus a margin while it runs and is charged what it bought, never more. A call whose maximum is above the limit is refused before anything is bought, with its estimate and maximum: ask the user, then call again with approvedMaxCostUsd set to the amount they approved.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"projectId": "<projectId>"
},
"name": "find_top_searches"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| contains | No | Text every keyword must contain, e.g. 'shoes'. | |
| minVolume | No | The least monthly search volume a keyword may have. | |
| projectId | Yes | Required. The Visibility Genies project this call works in and is billed to. Call list_projects to find one. | |
| languageCode | No | Language code such as en, es or vi. When left out, the language of the project's default market is used (see list_projects). | |
| locationCode | No | Market location code, for example 2840 for the United States. When left out, the project's default market is used (shown by list_projects and changed in project settings). A few countries, Iceland (2352) among them, only have Google Ads data: search volume, CPC and trends are available there, but keyword difficulty, search intent and domain analytics are not. | |
| maxDifficulty | No | The highest keyword difficulty (0 to 100) a keyword may have. | |
| approvedMaxCostUsd | No | The most, in USD, the user approved for this call after seeing its estimate and maximum. Only needed after a call was refused for costing more than the workspace's agent spend limit; never set it without asking the user. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cost | No | ||
| meta | No | ||
| bought | No | ||
| keywords | No | ||
| savedResultId | No |