Get ranked keywords
get_ranked_keywordsReturns the keywords a domain or page ranks for in a country-level market: keyword, position, search volume, traffic, CPC, keyword difficulty and URL. By default it asks for Domain Overview's Top keywords page (the 100 keywords with the most traffic), so a page bought here opens free in the app and one bought in the app, or for a new rank tracker's suggestions, is answered here at no charge. Use get_domain_overview for a domain's totals. Estimated price: ~$0.05 for 100 rows, billed by the rows returned; asking again within 12 hours is answered from the saved copy at no charge. 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>",
"target": "<target>"
},
"name": "get_ranked_keywords"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum rows to return (1-100). Defaults to 100; 50 or 100 at an offset that is a multiple of it reads and fills Domain Overview's Top keywords pages. | |
| scope | No | Which part of the site to research. One of: exact_url (a single page), subfolder (the path and everything under it), domain (the hostname without subdomains), subdomains (the hostname plus all of its subdomains). Defaults to subdomains for a bare domain and to subfolder when the input includes a path. | |
| market | No | Legacy US selector. An explicit locationCode wins over it; leave both out to use the project's market. | |
| offset | No | Rows to skip for pagination. | |
| sortBy | No | Sort order for returned rows. Defaults to traffic_estimate, Domain Overview's default. | |
| target | Yes | Domain without protocol or www (e.g. 'example.com'), or an absolute page URL. | |
| maxRank | No | Only return keywords ranking at this position or better. | |
| projectId | Yes | Required. The Visibility Genies project this call works in and is billed to. Call list_projects to find one. | |
| resultTypes | No | SERP result types to include. Omit for the default, which Domain Overview uses too. | |
| languageCode | No | Language for locationCode. Defaults to that location's primary language when locationCode overrides the project market. | |
| locationCode | No | Country-level location code. Defaults to the project's market; takes precedence over the legacy market object. | |
| minSearchVolume | No | Only return keywords with at least this monthly search volume. | |
| excludeBrandTerms | No | Exclude keywords containing any of these brand terms, each without commas or plus signs, as Domain Overview's exclude filter reads them. | |
| includeSubdomains | No | Deprecated: use scope ('subdomains' or 'domain') instead. | |
| 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 | ||
| scope | No | ||
| target | No | ||
| keywords | Yes | ||
| totalCount | Yes | ||
| savedResultId | No |