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

**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](https://thelastapi.dev/docs/actions) 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 as `low`, `medium`, or `high`.
- **`competition_index`**: A granular numeric score indicating advertiser competition for paid placement on that keyword.
- **`monthly`**: An array of 12 objects containing `year`, `month`, and `search_volume`, reflecting seasonal search volume fluctuations over the trailing year.

Here is a sample response payload returned by the API:

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

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

```bash
vibiz seo keywords "running shoes,trail running shoes" --location uk --language en --json
```

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

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

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

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

```ts
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, `location` defaults to `"United States"`.
- **`language`**: Accepts a two-letter language code (`"en"`, `"de"`, `"es"`) or a language name (`"English"`). If omitted, `language` defaults 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:

1. **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.
2. **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_ideas` action to generate keyword lists from seed phrases. See [Keyword ideas with volume and difficulty from one call](https://thelastapi.dev/blog/keyword-ideas-api) for implementation examples.
- **Inspect live rankings**: Once you identify high-volume terms, pass them to `seo.serp` to 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](https://thelastapi.dev/blog/scrape-website-to-markdown-api) or inspect search results with [A web search API for AI agents and apps](https://thelastapi.dev/blog/web-search-api-ai-agents).
- **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](https://thelastapi.dev/blog/agent-web-research-tools).

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](https://thelastapi.dev/docs/actions) 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"`.

---

Published 2026-11-15 · https://thelastapi.dev/blog/keyword-research-api-volume-cpc
