Tools

⌄

SEO tools

Keywords, rankings, SERPs, domains, backlinks, and technical audits.

15 tools are implemented in this family. The definitions below come from the service’s actual tool catalog.

Authenticate, inspect the schema, then request an estimate using dry_run where supported. Research can spend workspace credits.

Get keyword ideas

seo_search_keywords

Candidate keywords around a seed, with volume, difficulty, intent, CPC and trend for each. Use for "find keywords for X" or "keyword ideas for a page about X". Rows already carry the metrics, so do not call seo_get_keyword_metrics afterwards. For one query's top results use seo_get_serp. Returns a list; each row has keyword, volume, kd (0 to 100), intent, cpc (USD), competition (0 to 1), bid_low, bid_high (Google Ads top-of-page bid range, USD), trend[12] (month, volume). null = provider has no data; 0 = measured zero. Cost: 5 + 5 per 100 rows. Default 100 rows = 10 credits. Cached 7 days.

REST endpoint

POST /api/seo/tools/seo_search_keywords

Product-credit cost

5 + 5 per 100 rows. Default 100 rows = 10 credits. Cached 7 days.

Input JSON schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "seed": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Required. The seed keyword or topic."
    },
    "mode": {
      "default": "suggestions",
      "description": "suggestions: keywords that contain the seed. related: keywords whose results page is like the seed's. ideas: keywords in the same category.",
      "type": "string",
      "enum": [
        "suggestions",
        "related",
        "ideas"
      ]
    },
    "location": {
      "default": "United States",
      "description": "Provider location name or code. Default United States.",
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      ]
    },
    "language": {
      "default": "en",
      "description": "ISO 639-1 language code. Default en.",
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}(-[A-Za-z]{2,4})?$"
    },
    "limit": {
      "default": 100,
      "description": "Max rows. Default 100, cap 1000.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "cursor": {
      "description": "The next page: meta.cursor from the previous result.",
      "type": "string"
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "seed"
  ]
}

Check keyword metrics

seo_get_keyword_metrics

Volume, difficulty, intent, CPC and 12-month trend for keywords you already have, with AI-engine prompt volume on request (ai_volume: true). Not for discovering keywords: use seo_search_keywords. Returns one row per input keyword in the order given: keyword, volume, kd, intent, cpc, competition, bid_low, bid_high, trend[12], ai_volume, ai_trend[12]. With source google_ads, kd and intent are always null and keywords over 80 characters come back all null. ai_volume and ai_trend are null unless ai_volume is true. AI volume is DataForSEO's modelled estimate, not assistant logs. Cost: 5 + 5 per 100 keywords with source labs; 24 flat with source google_ads; ai_volume adds 4 + 4 per 100 keywords. Cached 7 days.

REST endpoint

POST /api/seo/tools/seo_get_keyword_metrics

Product-credit cost

5 + 5 per 100 keywords with source labs; 24 flat with source google_ads; ai_volume adds 4 + 4 per 100 keywords. Cached 7 days.

Input JSON schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "keywords": {
      "minItems": 1,
      "maxItems": 1000,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "description": "Required. At most 1000."
    },
    "source": {
      "default": "labs",
      "description": "labs, or google_ads for Keyword Planner's own volume (slower; no kd or intent).",
      "type": "string",
      "enum": [
        "labs",
        "google_ads"
      ]
    },
    "ai_volume": {
      "default": false,
      "description": "Also return AI-engine prompt volume.",
      "type": "boolean"
    },
    "location": {
      "default": "United States",
      "description": "Provider location name or code. Default United States.",
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      ]
    },
    "language": {
      "default": "en",
      "description": "ISO 639-1 language code. Default en.",
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}(-[A-Za-z]{2,4})?$"
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "keywords"
  ]
}

Get search results for a query

seo_get_serp

The top organic results and SERP features Google shows for one query: "what ranks for X", "is there a featured snippet or AI overview for X". For one site's position use seo_get_position. Returns features[], results[] (rank, organic_rank, type, url, domain, title, snippet, published_at, rating), related_searches[], ai_overview (text, references[]) or null, results_count, check_url. Each People Also Ask question and each forum thread is its own row at its block's rank. location localises the local pack, not the organic rows of a bare service search: put the town in the keyword. Cost: 1 credit per 10 results, +1 with ai_overview. Default top 10 = 1 credit. Cached 24 hours.

REST endpoint

POST /api/seo/tools/seo_get_serp

Product-credit cost

1 credit per 10 results, +1 with ai_overview. Default top 10 = 1 credit. Cached 24 hours.

Input JSON schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "keyword": {
      "type": "string",
      "minLength": 1,
      "maxLength": 700
    },
    "location": {
      "default": "United States",
      "description": "Provider location name or code. Default United States.",
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      ]
    },
    "language": {
      "default": "en",
      "description": "ISO 639-1 language code. Default en.",
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}(-[A-Za-z]{2,4})?$"
    },
    "device": {
      "default": "desktop",
      "type": "string",
      "enum": [
        "desktop",
        "mobile"
      ]
    },
    "depth": {
      "default": 10,
      "description": "How many results to fetch. Default 10, max 100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "ai_overview": {
      "default": false,
      "description": "Also return Google's AI overview and its cited sources. +1 credit.",
      "type": "boolean"
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "keyword"
  ]
}

Get a site's position for a keyword

seo_get_position

Where one target ranks for one keyword, scanning the top 100 server-side. For every keyword a domain ranks for use seo_get_ranked_keywords. Returns keyword, target, rank (absolute, null when not in the top 100), organic_rank, url, title, scanned_depth, above[] (rank, domain, url of the organic results ahead, at most 10). Cost: 6 credits flat, also when the target is not in the top 100. NoData (1 credit) only when the keyword has no organic results. Cached 24 hours.

REST endpoint

POST /api/seo/tools/seo_get_position

Product-credit cost

6 credits flat, also when the target is not in the top 100. NoData (1 credit) only when the keyword has no organic results. Cached 24 hours.

Input JSON schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "keyword": {
      "type": "string",
      "minLength": 1,
      "maxLength": 700
    },
    "target": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048,
      "description": "Domain or URL. example.com covers all subdomains, www.example.com is that host only, a full URL is that page only."
    },
    "location": {
      "default": "United States",
      "description": "Provider location name or code. Default United States.",
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      ]
    },
    "language": {
      "default": "en",
      "description": "ISO 639-1 language code. Default en.",
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}(-[A-Za-z]{2,4})?$"
    },
    "device": {
      "default": "desktop",
      "type": "string",
      "enum": [
        "desktop",
        "mobile"
      ]
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "keyword",
    "target"
  ]
}

Get a domain overview

seo_get_domain_overview

Traffic estimate, ranked keyword count, position spread, top pages and domain rank for one domain. The canonical source of domain rank. For the keywords behind the traffic use seo_get_ranked_keywords; for many domains use seo_get_domain_ratings or seo_get_traffic_estimates. Returns domain_rank (0 to 1000, DataForSEO's scale, not Ahrefs DR), organic_traffic, organic_keywords, organic_traffic_cost (USD), positions (top_3, top_10, top_100), keyword_changes (new, up, down, lost), paid_traffic, paid_keywords, top_pages[] (url, organic_traffic, organic_keywords), history[] (12 months: month, organic_traffic, organic_keywords) only with history true. Traffic is a modelled estimate. Cost: 15 credits; +56 with history. Cached 7 days.

REST endpoint

POST /api/seo/tools/seo_get_domain_overview

Product-credit cost

15 credits; +56 with history. Cached 7 days.

Input JSON schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "target": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048,
      "description": "Domain or URL. example.com covers all subdomains, www.example.com is that host only, a full URL is that page only."
    },
    "location": {
      "default": "United States",
      "description": "Provider location name or code. Default United States.",
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      ]
    },
    "language": {
      "default": "en",
      "description": "ISO 639-1 language code. Default en.",
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}(-[A-Za-z]{2,4})?$"
    },
    "history": {
      "default": false,
      "description": "Also return 12 months of organic traffic and keywords.",
      "type": "boolean"
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "target"
  ]
}

Get a domain's ranked keywords

seo_get_ranked_keywords

Keywords a domain or one page ranks for in the top 100, with position, URL and metrics. For keywords a competitor has that you do not, use seo_get_keyword_gap. Returns a list sorted by traffic: keyword, rank, type (organic, featured_snippet or local_pack), previous_rank (null = did not rank at the previous update), is_new, url, volume, kd, cpc, intent, traffic (estimated monthly visits), serp_features[]. rank counts every element on the page, so an organic top-100 keyword can read rank 104. Cost: 5 + 5 per 100 rows. Default 100 rows = 10 credits. Cached 7 days.

REST endpoint

POST /api/seo/tools/seo_get_ranked_keywords

Product-credit cost

5 + 5 per 100 rows. Default 100 rows = 10 credits. Cached 7 days.

Input JSON schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "target": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048,
      "description": "Domain or URL. example.com covers all subdomains, www.example.com is that host only, a full URL is that page only."
    },
    "location": {
      "default": "United States",
      "description": "Provider location name or code. Default United States.",
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      ]
    },
    "language": {
      "default": "en",
      "description": "ISO 639-1 language code. Default en.",
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}(-[A-Za-z]{2,4})?$"
    },
    "limit": {
      "default": 100,
      "description": "Max rows. Default 100, cap 1000.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "cursor": {
      "description": "The next page: meta.cursor from the previous result.",
      "type": "string"
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "target"
  ]
}

Find search competitors

seo_get_serp_competitors

Domains that share search results with a target, with how many keywords overlap. SERP competitors, not business competitors. Use before seo_get_keyword_gap to choose competitors. Returns a list sorted by shared keywords: domain, shared_keywords, avg_position, organic_traffic, organic_keywords, paid_traffic, paid_keywords. The target itself is excluded. Cost: 5 + 5 per 100 rows. Default 100 rows = 10 credits. Cached 7 days.

REST endpoint

POST /api/seo/tools/seo_get_serp_competitors

Product-credit cost

5 + 5 per 100 rows. Default 100 rows = 10 credits. Cached 7 days.

Input JSON schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "target": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048,
      "description": "Domain or URL. example.com covers all subdomains, www.example.com is that host only, a full URL is that page only."
    },
    "location": {
      "default": "United States",
      "description": "Provider location name or code. Default United States.",
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      ]
    },
    "language": {
      "default": "en",
      "description": "ISO 639-1 language code. Default en.",
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}(-[A-Za-z]{2,4})?$"
    },
    "limit": {
      "default": 100,
      "description": "Max rows. Default 100, cap 1000.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "cursor": {
      "description": "The next page: meta.cursor from the previous result.",
      "type": "string"
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "target"
  ]
}

Find keyword gaps

seo_get_keyword_gap

Keywords one competitor ranks for in the top 100 that the target does not rank for at all: "what does competitor.com rank for that we do not". Returns a list sorted by volume: keyword, competitor, competitor_rank, competitor_url, volume, kd, cpc, intent. Cost: 5 + 5 per 100 rows. Default 100 rows = 10 credits. Cached 7 days.

REST endpoint

POST /api/seo/tools/seo_get_keyword_gap

Product-credit cost

5 + 5 per 100 rows. Default 100 rows = 10 credits. Cached 7 days.

Input JSON schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "target": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048,
      "description": "Domain or URL. example.com covers all subdomains, www.example.com is that host only, a full URL is that page only."
    },
    "competitor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048,
      "description": "Required. One competitor's domain. A URL is read as its host."
    },
    "location": {
      "default": "United States",
      "description": "Provider location name or code. Default United States.",
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      ]
    },
    "language": {
      "default": "en",
      "description": "ISO 639-1 language code. Default en.",
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}(-[A-Za-z]{2,4})?$"
    },
    "limit": {
      "default": 100,
      "description": "Max rows. Default 100, cap 1000.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "cursor": {
      "description": "The next page: meta.cursor from the previous result.",
      "type": "string"
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "target",
    "competitor"
  ]
}

Get a backlink summary

seo_get_backlink_summary

Link totals for a domain or page: backlinks, referring domains, dofollow share, link types and domain rank. For individual links use seo_get_backlinks; for linking sites use seo_get_referring_domains. Returns domain_rank (equals seo_get_domain_overview's), backlinks, referring_domains, referring_main_domains, referring_ips, dofollow_share (0 to 1), broken_backlinks, broken_pages, spam_score (0 to 100), target_spam_score, first_seen, and top-10 counts by link type, attribute, placement, platform, TLD and country. Cost: 10 credits flat. Cached 7 days.

REST endpoint

POST /api/seo/tools/seo_get_backlink_summary

Product-credit cost

10 credits flat. Cached 7 days.

Input JSON schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "target": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048,
      "description": "Domain or URL. example.com covers all subdomains, www.example.com is that host only, a full URL is that page only."
    },
    "include_subdomains": {
      "default": true,
      "description": "Count links to subdomains too. Ignored for a URL target.",
      "type": "boolean"
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "target"
  ]
}

Get backlinks

seo_get_backlinks

Individual backlinks pointing at a domain or page, strongest referring domain first. status lost lists removed links. Returns a list: url_from, url_to, domain_from, dr_from (linking domain's rank, 0 to 1000), page_title, anchor, dofollow, rel[], type, spam_score (0 to 100), url_to_status, broken, first_seen, last_seen, lost (only with status lost or all). Cost: 10 + 1.5 per 100 rows. Default 100 rows = 12 credits. Cached 7 days.

REST endpoint

POST /api/seo/tools/seo_get_backlinks

Product-credit cost

10 + 1.5 per 100 rows. Default 100 rows = 12 credits. Cached 7 days.

Input JSON schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "target": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048,
      "description": "Domain or URL. example.com covers all subdomains, www.example.com is that host only, a full URL is that page only."
    },
    "include_subdomains": {
      "default": true,
      "description": "Count links to subdomains too. Ignored for a URL target.",
      "type": "boolean"
    },
    "status": {
      "default": "live",
      "description": "live: links found at the last check. lost: links since removed. all: both.",
      "type": "string",
      "enum": [
        "live",
        "lost",
        "all"
      ]
    },
    "limit": {
      "default": 100,
      "description": "Max rows. Default 100, cap 1000.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "cursor": {
      "description": "The next page: meta.cursor from the previous result.",
      "type": "string"
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "target"
  ]
}

Get referring domains

seo_get_referring_domains

Domains linking to a target, one row per domain, with the rank each passes, link counts and spam score. Good for link prospecting from a rival's profile; status lost lists sites that stopped linking. Returns a list sorted by rank_passed: domain, rank_passed (0 to 1000, the rank its links pass to the target, not the domain's own rank), backlinks, referring_pages, dofollow_backlinks, broken_backlinks, spam_score, first_seen, lost (only with status lost or all). Cost: 10 + 1.5 per 100 rows. Default 100 rows = 12 credits. Cached 7 days.

REST endpoint

POST /api/seo/tools/seo_get_referring_domains

Product-credit cost

10 + 1.5 per 100 rows. Default 100 rows = 12 credits. Cached 7 days.

Input JSON schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "target": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048,
      "description": "Domain or URL. example.com covers all subdomains, www.example.com is that host only, a full URL is that page only."
    },
    "include_subdomains": {
      "default": true,
      "description": "Count links to subdomains too. Ignored for a URL target.",
      "type": "boolean"
    },
    "status": {
      "default": "live",
      "description": "live: links found at the last check. lost: links since removed. all: both.",
      "type": "string",
      "enum": [
        "live",
        "lost",
        "all"
      ]
    },
    "limit": {
      "default": 100,
      "description": "Max rows. Default 100, cap 1000.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "cursor": {
      "description": "The next page: meta.cursor from the previous result.",
      "type": "string"
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "target"
  ]
}

Get domain ratings in bulk

seo_get_domain_ratings

Domain rank (and Ahrefs DR when configured) for up to 1,000 domains in one call. The cheap way to rate a list. Returns one row per distinct domain in first-given order: domain, domain_rank (0 to 1000, for the host as given; 0 for an unknown domain), ahrefs_dr (0 to 100 for the registered domain, null when Ahrefs did not answer). ahrefs_status: ok, partial, failed or not_configured. Wherever you show ahrefs_dr, show ahrefs_attribution's text linked to its url. errors[] lists inputs that were not valid domains. Cost: 7 + 2.5 per 100 domains. Default 100 domains = 10 credits. Cached 7 days, or 1 hour when ahrefs_status is not ok.

REST endpoint

POST /api/seo/tools/seo_get_domain_ratings

Product-credit cost

7 + 2.5 per 100 domains. Default 100 domains = 10 credits. Cached 7 days, or 1 hour when ahrefs_status is not ok.

Input JSON schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "targets": {
      "minItems": 1,
      "maxItems": 1000,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 2048
      },
      "description": "Required. At most 1000."
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "targets"
  ]
}

Get traffic estimates in bulk

seo_get_traffic_estimates

Estimated monthly organic and paid traffic for up to 1,000 domains in one call. For authority only, use seo_get_domain_ratings (a tenth of the cost). Returns one row per input domain in the order given: domain, organic_traffic, organic_keywords, paid_traffic. null = provider has no data. errors[] lists inputs that were not valid domains. Cost: 50 + 50 per 100 domains. Default 100 domains = 100 credits. Cached 7 days.

REST endpoint

POST /api/seo/tools/seo_get_traffic_estimates

Product-credit cost

50 + 50 per 100 domains. Default 100 domains = 100 credits. Cached 7 days.

Input JSON schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "targets": {
      "minItems": 1,
      "maxItems": 1000,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 2048
      },
      "description": "Required. At most 1000."
    },
    "location": {
      "default": "United States",
      "description": "Provider location name or code. Default United States.",
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      ]
    },
    "language": {
      "default": "en",
      "description": "ISO 639-1 language code. Default en.",
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}(-[A-Za-z]{2,4})?$"
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "targets"
  ]
}

Get an on-page snapshot

seo_get_page

An on-page snapshot of one URL, fetched live: title, meta description, canonical, robots, headings, word count, schema types and link counts. For a whole site use seo_run_technical_crawl. Returns url, final_url, status, title, meta_description, canonical, robots_meta, lang, h1[], h2[], word_count, schema_types[], links_internal, links_external, images, images_without_alt; with include, links[] (text, url) and text (without nav, header and footer). null = the tag is absent. Cost: 0 credits, rate limited. Cached 1 hour.

REST endpoint

POST /api/seo/tools/seo_get_page

Product-credit cost

0 credits, rate limited. Cached 1 hour.

Input JSON schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048,
      "description": "Required. An http or https URL."
    },
    "include": {
      "default": [],
      "description": "Also return the page's links, its visible text, or both.",
      "maxItems": 2,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "links",
          "text"
        ]
      }
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "url"
  ]
}

Run a technical audit

seo_run_technical_crawl

Crawl a site for technical SEO issues. Slow: returns a task_id at once; read the result with get_task. Does not run Lighthouse. When done, get_task returns target, pages_requested, pages_crawled, rendered, onpage_score, status_codes (crawled pages per HTTP status), broken_links, broken_resources, non_indexable, duplicate_titles, duplicate_descriptions, issues[] (check, pages, sample_urls[]). Results expire after 30 days. Cost: 5 credits per 100 pages; 50 per 100 pages rendered. Charged on max_pages requested, not pages crawled. 1,000 pages = 50 credits.

REST endpoint

POST /api/seo/tools/seo_run_technical_crawl

Product-credit cost

5 credits per 100 pages; 50 per 100 pages rendered. Charged on max_pages requested, not pages crawled. 1,000 pages = 50 credits.

Input JSON schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "target": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048,
      "description": "Required. A domain or host. Only that host is crawled."
    },
    "max_pages": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000,
      "description": "Required. Pages to crawl."
    },
    "render": {
      "default": false,
      "description": "Execute JavaScript. 10x the cost.",
      "type": "boolean"
    },
    "include_subdomains": {
      "default": false,
      "description": "Follow links onto the target's subdomains too; they share max_pages.",
      "type": "boolean"
    },
    "idempotency_key": {
      "description": "Retry-safe key: the same key returns the same task.",
      "type": "string",
      "minLength": 8,
      "maxLength": 128
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    }
  },
  "required": [
    "target",
    "max_pages"
  ]
}