Keyword research
Turn seeds into scored keywords, look up metrics for a list you already have, and save the ones worth keeping.
Volume is monthly searches. KD is keyword difficulty from 0 to 100. CPC is in USD. Competition is paid competition from 0 to 1. A — in any cell means the provider had no value.
research_keywords
Expand seed keywords into related keywords with search volume, difficulty, CPC, competition, and intent. Costs credits, roughly 30 to 100 per seed depending on the data source.
| Argument | Type | Required | Default | Meaning |
|---|---|---|---|---|
projectId | string | yes | ||
seeds | string[], 1 to 5 items, each up to 200 chars | yes | Seed keywords, researched together in one call. Prefer one call with several seeds over several single-seed calls. | |
locationCode | integer | no | project market | |
languageCode | string | no | project market | |
limit | integer, 1 to 500 | no | 100 | Maximum rows to return. |
includeClickstreamData | boolean | no | false | Refine volumes with clickstream data, which splits Google Ads' grouped close variants (plurals, misspellings). Doubles the credit cost. |
Returns: the keyword rows, the provider and sources used, and the cost in USD. Results are also written to the project's metrics cache, so saving them later and viewing them in the dashboard does not buy the data twice.
In countries whose data comes from Google Ads rather than a clickstream source, difficulty and intent are unavailable and includeClickstreamData has no effect.
get_keyword_metrics
Look up volume, difficulty, CPC, and competition for an exact list of keywords, with no expansion. Use it to score a list you already have; use research_keywords to discover new ones. Costs credits per batch.
| Argument | Type | Required | Default | Meaning |
|---|---|---|---|---|
projectId | string | yes | ||
keywords | string[], 1 to 700 items, each up to 200 chars | yes | Exact terms to look up. Batch up to 700 in one call. | |
locationCode | integer | no | project market | |
languageCode | string | no | project market |
Returns: one row per keyword that had data, and an explicit list of the keywords the provider returned nothing for, so a missing row is never mistaken for a zero.
save_keywords
Add keywords to the project's saved list, where you can tag and track them in the dashboard. Free; no provider call. Duplicates in the same market are ignored, so the call is safe to repeat.
| Argument | Type | Required | Default | Meaning |
|---|---|---|---|---|
projectId | string | yes | ||
keywords | string[], 1 to 500 items | yes | Keywords to save. | |
locationCode | integer | no | project market | |
languageCode | string | no | project market |
list_saved_keywords
The project's saved keywords with their cached metrics. Free; reads stored data, so metrics are as fresh as the last research or refresh that touched them.
| Argument | Type | Required | Default | Meaning |
|---|---|---|---|---|
projectId | string | yes | ||
search | string, up to 200 chars | no | Substring filter on the keyword text. |