A keyword research API: search volume, CPC and competition
Query Google search volume, CPC, and competition for up to 1,000 keywords per call using thelastapi's keyword research API and CLI.
On this page 8 sections
- What data the keyword search volume API returns
- Querying keyword search volume from the CLI
- Fetching keyword metrics via HTTP and TypeScript
- Targeting locations, cities and languages
- Batching up to 1,000 keywords and managing rate limits
- Pricing and cost tracking per call
- Combining keyword search volume with related SEO actions
- FAQ
You can get Google search volume, cost per click, and advertiser competition for up to 1,000 keywords in a single call using the seo.keywords action. thelastapi queries live Google Ads search data and returns 12-month search averages, monthly volume breakdowns, competition indices, and USD CPC estimates. Everything runs through one unified endpoint, CLI command, or SDK call using a single API key and shared credit balance.
This guide explains what the keyword research API returns, how to batch queries efficiently, and how to query search metrics from the command line, HTTP endpoints, or your application code.
What data the keyword search volume API returns
The seo.keywords action accepts a list of search terms and pulls metrics directly from Google's search data. It is documented on the Web data: scrape, search, SEO, ads library page alongside other research tools.
Each keyword entry in the response returns five core fields:
search_volume: The 12-month average monthly search volume for the keyword in your target location and language.cpc_usd: The estimated cost per click in USD that advertisers pay when bidding on that keyword in Google Ads.competition: The categorical competition tier for the search term, reported aslow,medium, orhigh.competition_index: A granular numeric score indicating advertiser competition for paid placement on that keyword.monthly: An array of 12 objects containingyear,month, andsearch_volume, reflecting seasonal search volume fluctuations over the trailing year.
Here is a sample response payload returned by the API:
{
"location": "United States",
"language": "en",
"keywords": [
{
"keyword": "running shoes",
"search_volume": 246000,
"cpc_usd": 1.42,
"competition": "high",
"competition_index": 89,
"monthly": [
{ "year": 2024, "month": 3, "search_volume": 246000 },
{ "year": 2024, "month": 4, "search_volume": 301000 }
]
}
]
}The returned payload gives you structured historical figures instead of rough estimates, making it useful for content planning, building internal marketing dashboards, or feeding live data into an autonomous research agent.
Querying keyword search volume from the CLI
You can query search metrics directly in your terminal using the vibiz CLI without configuring external client libraries. Pass a comma-separated list of terms to vibiz seo keywords:
vibiz seo keywords "running shoes,trail running shoes,best running shoes"The CLI prints the volume, CPC, and competition figures in a clean terminal table. You can also target specific locations, switch languages, or output raw JSON for pipeline processing:
vibiz seo keywords "running shoes,trail running shoes" --location uk --language en --jsonIf you want to run the action through the generic runner rather than the dedicated SEO command, pass your input parameters as a JSON string to vibiz run:
vibiz run seo.keywords --input '{"keywords":["running shoes","hiking boots"]}'Every run is logged under your account. You can inspect previous requests at any time by running vibiz runs --action seo.keywords or by looking up a specific run using its identifier with vibiz runs arun_123.
Fetching keyword metrics via HTTP and TypeScript
When building keyword lookups into an application, you can query the API using standard HTTP or the official client library.
Calling the endpoint with HTTP
Send a POST request to https://thelastapi.dev/v1/actions/seo.keywords with your Bearer token:
curl https://thelastapi.dev/v1/actions/seo.keywords \
-H "Authorization: Bearer $VIBIZ_API_KEY" \
-H "content-type: application/json" \
-d '{
"input": {
"keywords": ["running shoes", "trail running shoes"],
"location": "United States",
"language": "en"
}
}'The server returns an action result envelope:
{
"object": "action_result",
"action": "seo.keywords",
"output": {
"location": "United States",
"language": "en",
"keywords": [
{
"keyword": "running shoes",
"search_volume": 246000,
"cpc_usd": 1.42,
"competition": "high",
"competition_index": 89,
"monthly": [
{ "year": 2024, "month": 3, "search_volume": 246000 }
]
}
]
},
"cost_micro_usd": 80000,
"run_id": "arun_kw123",
"console_url": "https://thelastapi.dev/web-data?action=seo.keywords&run=arun_kw123"
}The cost_micro_usd field shows the precise upstream cost of the execution before margin, allowing you to log exact execution spend next to your application logs.
Calling the endpoint in TypeScript
In a Node.js or web app using @vibiz/app, call vibiz.actions.run:
import { vibiz } from '@vibiz/app';
const { output } = await vibiz.actions.run('seo.keywords', {
keywords: ['running shoes', 'trail running shoes', 'marathon shoes'],
location: 'United States',
language: 'en',
});
for (const entry of output.keywords) {
console.log(`${entry.keyword}: ${entry.search_volume}/mo ($${entry.cpc_usd} CPC, competition: ${entry.competition})`);
}When you use @vibiz/app with VIBIZ_APP_KEY, the cost is billed directly to that project and tracked in project usage reports.
Targeting locations, cities and languages
Search habits change by country and region. The seo.keywords action supports granular geographical and language targeting using two optional parameters:
location: Accepts a country name ("United States","United Kingdom"), a country code ("us","uk","de"), or a specific regional path down to the city level ("Austin,Texas,United States"). If omitted,locationdefaults to"United States".language: Accepts a two-letter language code ("en","de","es") or a language name ("English"). If omitted,languagedefaults to"English".
If you specify an unrecognized country or language, the API returns a 400 invalid_request error identifying the invalid field in details.field.
Batching up to 1,000 keywords and managing rate limits
Because keyword research often involves comparing hundreds of search queries, seo.keywords allows you to send anywhere from 1 to 1,000 keywords in a single call. Each individual keyword string can be up to 80 characters long.
Batching keywords into larger requests is important for two reasons:
- Efficiency and throughput: The action is capped at about 12 calls per minute. If you send individual keywords one call at a time, you will hit rate limits after a dozen terms. If you batch 500 or 1,000 keywords per call, you can evaluate 12,000 keywords per minute.
- Cost predictability: Querying a batch of up to 1,000 keywords costs about 8 cents upstream, making bulk lookups far more economical than single-item requests.
If you exceed 12 calls in a minute, the endpoint returns a 429 rate_limited status with a retry_after parameter in the error details. When that happens, your application should wait the specified number of seconds or pack more terms into each request payload.
Pricing and cost tracking per call
thelastapi bills web data actions from your account credit balance. Each call returns cost_micro_usd in its JSON envelope, which is the upstream cost of running the action. Your account is billed that cost plus the 30% web data margin.
| Operation | Upstream Cost | Notes |
|---|---|---|
seo.keywords | ~8 cents ($0.08) | Batches of 1 to 1,000 keywords per request |
seo.keyword_ideas | 1–4 cents | 1 to 20 seed keywords, returns ideas with difficulty |
seo.serp | Fraction of a cent | Live Google search results up to depth 100 |
seo.domain | 1–4 cents | Organic traffic estimate, top keywords, competitors |
seo.audit | Fraction of a cent | On-page SEO health check and issue scoring |
Every request also counts toward your account's daily spend ceiling ($5 per day by default, shared with AI model calls), which account owners can adjust inside billing settings. If your credits run out, the endpoint answers with 402 payment_required.
Combining keyword search volume with related SEO actions
Keyword search volume is only one part of search research. thelastapi provides complementary actions that you can combine in the same pipeline:
- Generate seed variations: If you do not have a keyword list ready, use the
seo.keyword_ideasaction to generate keyword lists from seed phrases. See Keyword ideas with volume and difficulty from one call for implementation examples. - Inspect live rankings: Once you identify high-volume terms, pass them to
seo.serpto see who currently ranks in Google's organic blue links and SERP feature blocks. - Gather page content: Once you identify competitors ranking for your keywords, fetch their content with Scrape a website to markdown with one API call or inspect search results with A web search API for AI agents and apps.
- Run AI agent workflows: When an autonomous agent is evaluating market demand, it can run
vibiz_seo { action: "keywords", input: { keywords: [...] } }directly over the MCP tool interface. Learn how to configure these tools in Give an agent web research tools: search, scrape and crawl.
To get started, explore the available parameters in the console under Web data, run your first batch via vibiz seo keywords, or consult the full reference on the Web data: scrape, search, SEO, ads library docs page.
Frequently asked questions
How many keywords can I query in a single request?
You can submit between 1 and 1,000 keywords per call in the `seo.keywords` action, with each keyword up to 80 characters long.
What rate limits apply to the keyword research API?
The `seo.keywords` action is capped at approximately 12 calls per minute; exceeding this rate returns a 429 status code with a `retry_after` duration in seconds.
How much does a keyword volume lookup cost?
A batch of up to 1,000 keywords costs about 8 cents upstream, billed with a 30% margin against your account credit balance.
What geographic locations can I target?
You can target countries by name (such as `"United States"`), country codes (like `"us"` or `"uk"`), or specific cities using a path format like `"Austin,Texas,United States"`.