Keyword researchGET$0.05

/v1/keyword-ideas

Keyword research with the numbers attached: every result contains your seed, and arrives with search volume, CPC, difficulty and intent.

The gap between the other two keyword calls. /v1/keyword-suggest gives you phrasings from public autocomplete but no numbers; /v1/keyword-metrics gives numbers for a list you already have, capped at 20. This one takes a single seed and returns up to 100 keywords that contain it, each with the full metric set, ordered by search volume — which is what a keyword-research session actually needs.

Matching is full text on the seed, so a search for "reksadana" returns reksadana keywords. Paid data, so it also covers terms autocomplete never surfaces.

totalFound reports how many the index holds for the seed, so you can see how much is below your limit.

Parameters #

Name		Description
`seed`	required	keyword to research (1–80 chars)
`limit`	optional	ideas to return, 1–100 (default 50)
`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.

request

GET https://citable.run/v1/keyword-ideas?seed=seo+api&limit=50

Response #

200 with the JSON below (trimmed) and the settlement signature in the PAYMENT-RESPONSE header. Every paid response also carries price and cluster.

200 · application/json

{
  "seed": "seo api",
  "country": "us",
  "lang": "en",
  "keywords": [
    { "keyword": "seo api", "volume": 390, "cpc": 20.98, "competition": "low", "difficulty": 40, "intent": "commercial" },
    { "keyword": "seo api free", "volume": 210, "cpc": 8.4, "competition": "low", "difficulty": 32, "intent": "commercial" },
    { "keyword": "google seo api", "volume": 170, "cpc": 12.1, "competition": "medium", "difficulty": 55, "intent": "informational" }
  ],
  "totalFound": 1840,
  "source": "dataforseo_labs",
  "price": "$0.05",
  "cluster": "mainnet"
}

Errors #

Any non-200 cancels the payment — errors are free.

Status	Code	When
400	`invalid_seed`	seed missing or longer than 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.

mcp

citable_keyword_ideas(seed, limit?, country?, lang?)   $0.05

Source & latency #

Data source	Typical latency
DataForSEO Labs (clickstream-derived)	~3–6 s

Note

Start here for a new topic. Reach for keyword-suggest when you want the exact question phrasings real people type, and keyword-metrics when you already have a shortlist to price.