Keyword ideas with volume and difficulty from one call
Generate keyword ideas with monthly search volume, CPC, competition, and difficulty in one API call using the seo.keyword_ideas action.
On this page 6 sections
Yes: you can generate keyword ideas alongside search volume, cost per click, competition, and difficulty in a single API call using the seo.keyword_ideas action. thelastapi provides this through a unified endpoint where you pass between 1 and 20 seed terms and receive a clean JSON list of related searches with live search metrics. One request delivers both paid ad competition and organic ranking difficulty without requiring multiple services or separate keys.
This guide covers how the keyword ideas API works, how to run it from the CLI, HTTP requests, or code, and how to filter results by location and language.
What comes back from the keyword ideas endpoint
When you call seo.keyword_ideas, you provide seed terms and receive an array of suggested keywords. Each suggestion includes metrics drawn from Google Ads and search engine results pages:
keyword: The suggested search phrase related to your seed terms.search_volume: The 12-month average monthly search volume.cpc_usd: The estimated cost per click in USD for advertisers bidding on the term.competition: The advertiser competition level, returned aslow,medium, orhigh.difficulty: The organic ranking difficulty score, showing how competitive the search results page is for organic positioning.
The response wrapper also returns the resolved location, language, and the total number of ideas found.
{
"location": "United States",
"language": "en",
"ideas": [
{
"keyword": "best trail running shoes",
"search_volume": 40500,
"cpc_usd": 1.42,
"competition": "high",
"difficulty": 58
},
{
"keyword": "waterproof trail running shoes",
"search_volume": 12100,
"cpc_usd": 1.15,
"competition": "medium",
"difficulty": 42
}
],
"total": 50
}Every response also reports metadata about the run, including cost_micro_usd, the unique run_id, and a console_url where you can view the run inside the web console.
How to call the keyword ideas API
You can trigger keyword research through the vibiz CLI, directly through HTTP, or inside an application using @vibiz/app.
Using the CLI
The fastest way to test ideas from your terminal is the vibiz seo ideas command. Pass a seed keyword and an optional limit:
vibiz seo ideas "running shoes" --limit 50You can also pass multiple seeds or customize geographic parameters:
vibiz seo ideas "running shoes" --location "United States" --language en --jsonIf you prefer to execute the raw action name, use vibiz run:
vibiz run seo.keyword_ideas --input '{"keywords":["running shoes","trail running shoes"],"limit":25}'Using HTTP and curl
For custom backends or languages without an official SDK, make a POST request to https://thelastapi.dev/v1/actions/seo.keyword_ideas:
curl https://thelastapi.dev/v1/actions/seo.keyword_ideas \
-H "Authorization: Bearer $VIBIZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": {
"keywords": ["mechanical keyboard", "custom keyboard"],
"location": "United States",
"language": "en",
"limit": 50
}
}'The endpoint runs synchronously. It accepts the input payload, queries Google keyword data, formats the response, and returns the result.
Using the TypeScript SDK
If your project runs with @vibiz/app, you can call the action directly through vibiz.actions.run. The app key handles authentication automatically:
import { vibiz } from '@vibiz/app';
interface KeywordIdea {
keyword: string;
search_volume: number;
cpc_usd: number;
competition: 'low' | 'medium' | 'high';
difficulty: number;
}
interface KeywordIdeasOutput {
location: string;
language: string;
ideas: KeywordIdea[];
total: number;
}
const { output, cost_micro_usd } = await vibiz.actions.run<KeywordIdeasOutput>(
'seo.keyword_ideas',
{
keywords: ['standing desk', 'ergonomic chair'],
location: 'United States',
language: 'en',
limit: 100,
}
);
console.log(`Discovered ${output.ideas.length} ideas. Call cost: $${cost_micro_usd / 1_000_000}`);
for (const idea of output.ideas) {
console.log(`${idea.keyword} | Vol: ${idea.search_volume} | Diff: ${idea.difficulty}`);
}Targeting locations and languages
Keyword volumes and competition vary significantly by market. The seo.keyword_ideas action accepts standard identifiers for regional queries:
location: Specify a country by name ("United States","United Kingdom"), a two-letter country code ("us","de","uk"), or a city path (such as"Austin,Texas,United States"). The default is"United States".language: Provide a two-letter language code ("en","de","es") or a full name ("English"). The default is"en".
If an invalid country or unsupported language string is provided, the API returns a 400 invalid_request status code with details.field set to "location" or "language".
vibiz seo ideas "kaffee" --location de --language de --limit 25How keyword ideas fit into SEO workflows
Generating ideas is usually the starting point of an SEO pipeline. After identifying candidate terms, you might check specific historical volumes, verify the live search layout, or evaluate your own content.
| Action | Primary Input | Key Output Metrics | Best For | Typical Cost |
|---|---|---|---|---|
seo.keyword_ideas | 1–20 seed terms | Ideas, search_volume, cpc_usd, competition, difficulty | Discovering related keywords and topical gaps | 1–4 cents |
seo.keywords | 1–1000 known terms | Monthly historical volume array, cpc_usd, competition_index | Verifying metrics for a known keyword list | ~8 cents per batch |
seo.serp | 1 keyword | Ranked URLs, domains, SERP features (answer boxes, AI overviews) | Checking who ranks and SERP composition | Fraction of a cent |
seo.audit | 1 page URL | Page speed, missing tags, H1 check, crawl issues | Auditing on-page content optimization | Fraction of a cent |
If you already have a predefined list of hundreds of terms from competitor analysis, switch to seo.keywords. It processes up to 1,000 terms in a single call to pull monthly historical search breakdowns. See a keyword research API: search volume, CPC and competition for batch processing workflows.
Once you pick promising keywords, check which pages currently rank using seo.serp, or run an on-page SEO audit from one API call to diagnose existing articles on your domain. If you want to analyze competing landing pages in detail, you can also scrape a website to markdown with one API call using web.scrape.
Tracking runs, costs, and limits
All calls to web data actions are logged automatically. You can review your past activity in the web console under Web data, or inspect previous requests using the CLI:
# List recent action executions
vibiz runs --action seo.keyword_ideas --since 1d
# Fetch the exact output of a specific run
vibiz runs arun_123456You can also fetch past runs programmatically using the HTTP API:
curl https://thelastapi.dev/v1/actions/runs/arun_123456 \
-H "Authorization: Bearer $VIBIZ_API_KEY"Pricing and billing limits
- Cost: A single
seo.keyword_ideasrequest typically costs between 1 and 4 cents, depending on the number of seeds and returned ideas. Every response includescost_micro_usd. The final amount billed to your credit balance includes this raw cost plus the standard 30% margin on web data. - Daily spend limit: Every account starts with a $5 per day ceiling shared between web data actions and AI calls. The account owner can adjust this threshold in the Billing settings.
- Rate limits: If you exceed your spend threshold, the API responds with
429 rate_limited.
Handling common errors
| Status Code | Code | Cause | Solution |
|---|---|---|---|
| 400 | invalid_request | Missing keywords array, more than 20 seeds, or unknown location. | Check details.field and adjust the parameter format. |
| 402 | payment_required | The account is out of credits. | Run vibiz billing top-up or add funds in the billing console. |
| 429 | rate_limited | Daily account spend limit reached. | Raise the daily ceiling in Billing or wait until midnight UTC. |
| 503 | provider_unavailable | External data provider timed out or is temporarily paused. | Retry the request or reduce the limit parameter. |
To explore all input options, review the full reference documentation on Web data: scrape, search, SEO, ads library. Create your account at thelastapi.dev/start to get the unified API key for web actions, hosting, and databases.
Frequently asked questions
How many seed keywords can I pass into the keyword ideas API at once?
You can provide between 1 and 20 seed keywords per request in the `keywords` array. The API generates up to 1,000 related ideas based on those seeds.
What is the difference between competition and difficulty?
`competition` measures paid search advertiser demand on Google Ads and returns `low`, `medium`, or `high`. `difficulty` is a numerical score representing how hard it is to rank on the first page of organic search results.
How much does calling the keyword ideas action cost?
A typical `seo.keyword_ideas` call costs between 1 and 4 cents. The exact cost is returned in the response as `cost_micro_usd`, billed against your account balance plus the 30% web data margin.
Can I target specific cities for localized keyword suggestions?
Yes. The `location` field accepts cities using path notation, such as `"Austin,Texas,United States"`, alongside country names and two-letter country codes.