# 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.

**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 as `low`, `medium`, or `high`.
- **`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.

```json
{
  "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:

```bash
vibiz seo ideas "running shoes" --limit 50
```

You can also pass multiple seeds or customize geographic parameters:

```bash
vibiz seo ideas "running shoes" --location "United States" --language en --json
```

If you prefer to execute the raw action name, use `vibiz run`:

```bash
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`:

```bash
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:

```ts
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"`.

```bash
vibiz seo ideas "kaffee" --location de --language de --limit 25
```

## How 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](https://thelastapi.dev/blog/keyword-research-api-volume-cpc) 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](https://thelastapi.dev/blog/on-page-seo-audit-api) 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](https://thelastapi.dev/blog/scrape-website-to-markdown-api) 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:

```bash
# List recent action executions
vibiz runs --action seo.keyword_ideas --since 1d

# Fetch the exact output of a specific run
vibiz runs arun_123456
```

You can also fetch past runs programmatically using the HTTP API:

```bash
curl https://thelastapi.dev/v1/actions/runs/arun_123456 \
  -H "Authorization: Bearer $VIBIZ_API_KEY"
```

### Pricing and billing limits

- **Cost**: A single `seo.keyword_ideas` request typically costs between 1 and 4 cents, depending on the number of seeds and returned ideas. Every response includes `cost_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](https://thelastapi.dev/docs/actions). Create your account at [thelastapi.dev/start](https://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.

---

Published 2026-11-15 · https://thelastapi.dev/blog/keyword-ideas-api
