Keyword researchGET$0.03
/v1/keyword-metrics
Search volume, CPC, competition, difficulty and intent per keyword — one price for a batch of up to 20.
Licensed clickstream-derived estimates, not a Google Keyword Planner passthrough. Answers come back in request order, and a keyword the source does not know returns null metrics rather than being dropped — so the array always lines up with what you sent.
Parameters#
| Name | Description | |
|---|---|---|
keywords | required | comma list of 1–20 keywords (each ≤80 chars) |
country | optional | 2-letter country code, default us |
lang | optional | 2-letter language code, default en |
Request#
Plain GET. Without a payment header the response is a 402 carrying the price; an x402 client pays and retries on its own — see the quickstart.
GET https://citable.run/v1/keyword-metrics?keywords=seo+api,rank+tracker
Response#
200 with the JSON below (trimmed) and the settlement signature in the PAYMENT-RESPONSE header. Every paid response also carries price and cluster.
{
"keywords": [
{ "keyword": "seo api", "volume": 390, "cpc": 20.98, "competition": "low", "difficulty": 40, "intent": "commercial" },
{ "keyword": "rank tracker", "volume": 5400, "cpc": 20.87, "competition": "low", "difficulty": 88, "intent": "informational" }
],
"requested": 2,
"matched": 2,
"country": "us",
"lang": "en",
"source": "dataforseo_labs",
"price": "$0.03",
"cluster": "mainnet"
}Errors#
Any non-200 cancels the payment — errors are free.
| Status | Code | When |
|---|---|---|
| 400 | invalid_keywords | empty list, more than 20, or a keyword over 80 chars |
| 400 | invalid_locale | country or lang is not a 2-letter code |
| 502 | upstream_failed | the data source did not answer — nothing is charged |
| 503 | not_configured | this deployment has no credentials for the source — nothing is charged |
MCP tool#
The same call from Claude, Codex or Cursor once citable-mcp is installed. Arguments mirror the parameters above.
citable_keyword_metrics(keywords, country?, lang?) $0.03Source & latency#
| Data source | Typical latency |
|---|---|
| DataForSEO Labs (clickstream-derived) | ~5–7 s |