Competitive researchGET$0.03

/v1/domain-history

A domain's organic footprint month by month — keywords, top-10 count, traffic — with the trend.

The stateless answer to "track my rankings". The ranking index already keeps a monthly history of every domain, so one call returns up to 24 months of it (the current month may be partial): how many keywords ranked, how many sat in the top 10, estimated traffic and its value, and how many keywords were new, moved up, moved down or dropped out each month. Nothing is stored on our side and there is no account to keep it in — run it again next month and the new month is there.

trend compares the first and last month in the window for keywords, top10 and estTraffic.

Parameters #

Name		Description
`domain`	required	hostname to track, e.g. example.com
`months`	optional	calendar months of history, 2–24 (default 12)
`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/domain-history?domain=ahrefs.com&months=2

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

{
  "domain": "ahrefs.com",
  "country": "us",
  "lang": "en",
  "months": [
    { "month": "2026-06", "organic": { "keywords": 118200, "top3": 7900, "top10": 24100, "estTraffic": 1270000, "estTrafficValue": 2210000, "new": 4100, "up": 9800, "down": 8700, "lost": 3900 }, "paid": { "keywords": 22, "estTraffic": 1300 } },
    { "month": "2026-07", "organic": { "keywords": 120400, "top3": 8100, "top10": 24800, "estTraffic": 1310000, "estTrafficValue": 2280000, "new": 4400, "up": 10200, "down": 8300, "lost": 3700 }, "paid": { "keywords": 25, "estTraffic": 1400 } }
  ],
  "trend": {
    "keywords": { "first": 118200, "last": 120400, "delta": 2200, "deltaPct": 1.9 },
    "top10": { "first": 24100, "last": 24800, "delta": 700, "deltaPct": 2.9 },
    "estTraffic": { "first": 1270000, "last": 1310000, "delta": 40000, "deltaPct": 3.1 }
  },
  "source": "dataforseo_labs",
  "price": "$0.03",
  "cluster": "mainnet"
}

Errors #

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

Status	Code	When
400	`invalid_domain`	domain is not a hostname
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_domain_history(domain, months?, country?, lang?)   $0.03

Source & latency #

Data source	Typical latency
DataForSEO Labs ranking index (monthly)	~2–5 s

Note

Monthly resolution — for today's position on one keyword use rank-check; for daily tracking, the rank-tracking skill keeps the history in your own repo.