Docs
Sign inStart free

SEO Domain Endpoints

All four operations are part of All tools. A start needs the relevant scope and enough credits, and the tool must be available in /v1/health. Free credits also follow the free limits. Accepted starts return 202 Accepted.

All four endpoints are preview, with paid and bounded free access:

  • Domain overview: authority, backlink summary, estimated organic traffic and keyword count.
  • Backlinks: single backlinks, or one row per linking domain.
  • Keywords a domain ranks for: up to 1,000 Google keywords with position, ranking URL, volume, CPC, difficulty and estimated traffic.
  • Search traffic of a domain: current estimated Google traffic and up to 24 months of monthly history.

POST/v1/seo/domains/overview

Returns a bounded domain intelligence snapshot: authority, referring-domain and backlink summaries, estimated organic traffic and ranking keyword count, top anchors, top pages, competitor hints, freshness, availability, and confidence.

Required Access

  • Access: Paid plans that include this family, or free credits (guest trial or verified account) within the free limits.
  • Operation family: SEO
  • Scope: api:seo:read
  • Credits: 35 credits reserved on acceptance
  • Idempotency: Idempotency-Key header required

Request

curl -X POST https://www.chab.ai/v1/seo/domains/overview \
  -H "Authorization: Bearer CHAB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: domain-overview-001" \
  -d '{"domain":"example.com","include_subdomains":false,"location":{"country":"US"},"language":"en-US"}'

{
  "domain": "example.com",
  "include_subdomains": false,
  "location": {
    "country": "US"
  },
  "language": "en-US"
}

Fields:

  • domain: required hostname or HTTPS URL. Chab normalizes any accepted host to the registrable domain, such as example.co.uk. HTTPS URL paths become path_scope when path_scope is omitted.
  • include_subdomains: optional boolean, default false.
  • path_scope: optional path beginning with / or a same-domain HTTPS URL. The normalized prefix is capped at 512 characters.
  • location.country: optional ISO 3166-1 alpha-2 country code. It picks the Google market for the organic traffic and keyword count, the US when omitted. Backlink coverage is global.
  • language: optional BCP 47 language tag. It picks the market language for the organic traffic and keyword count, the country's main language when omitted. It does not narrow backlink coverage.
  • callback_url, callback_secret, callback_events, and callback_notify_on_expiration: optional one-off operation callback fields.

Unknown fields are rejected. filters, sort, limit, output_format, and artifact/output-mode fields are not accepted on this endpoint.

Async Response

{
  "operation": {
    "id": "op_01JZ7H0A1B2C3D4E5F6G7H8J9K",
    "status": "queued",
    "operation_key": "seo.domains.overview",
    "family": "seo",
    "status_url": "/v1/operations/op_01JZ7H0A1B2C3D4E5F6G7H8J9K",
    "result_url": "/v1/operations/op_01JZ7H0A1B2C3D4E5F6G7H8J9K/result",
    "estimated_credits": 35,
    "result_available": false,
    "warnings": []
  },
  "meta": {
    "request_id": "req_123",
    "credits": {
      "estimated": 35,
      "reserved": 35,
      "currency": "credit"
    }
  }
}

Succeeded Status

GET /v1/operations/{id} returns the operation status. Domain operations are asynchronous Chab operations; there is no public provider task handle.

Result

GET /v1/operations/{id}/result returns a compact inline result:

{
  "data": {
    "result": {
      "domain": "example.com",
      "include_subdomains": false,
      "path_scope": null,
      "location": {
        "country": "US"
      },
      "language": "en-US",
      "fetched_at": "2026-06-29T12:00:05+00:00",
      "authority": {
        "score": 73
      },
      "visibility": {
        "organic_keywords": 4210,
        "organic_traffic": 18450,
        "indexed_pages": null
      },
      "referring_domains": {
        "total": 38,
        "main_domains": 31,
        "follow": 26,
        "nofollow": 12
      },
      "backlinks": {
        "total": 120,
        "follow": 84,
        "nofollow": 36,
        "broken": 3,
        "spam_score": 2,
        "first_seen": "2025-01-01T00:00:00+00:00",
        "last_seen": "2026-06-20T00:00:00+00:00"
      },
      "top_anchors": [],
      "top_pages": [],
      "competitors": [],
      "availability": {
        "authority.score": "available",
        "visibility.organic_keywords": "available",
        "visibility.organic_traffic": "available",
        "visibility.indexed_pages": "unavailable"
      },
      "confidence": {
        "score": 1,
        "availability": "available",
        "source": "chab"
      },
      "complete": true
    },
    "artifacts": [],
    "warnings": [],
    "result_expires_at": "2026-07-02T12:00:05+00:00"
  },
  "meta": {
    "request_id": "req_123"
  }
}

Top anchors, top pages, and competitor hints are each capped at 10 rows. visibility.organic_traffic is the estimated monthly organic Google visits and visibility.organic_keywords the number of keywords the domain ranks for, in the requested market. indexed_pages is not part of this dataset and stays null. A metric that could not be read is null with unavailable availability; missing metrics are never converted to numeric zero.

POST/v1/seo/domains/backlinks

Returns backlink rows and referring-domain aggregates for a normalized domain. Small result sets stay inline. Larger result sets are exported as protected JSONL operation artifacts. With group: "referring_domains" it returns one row per linking domain instead, every row inline up to limit.

Required Access

  • Access: Paid plans that include this family, or free credits (guest trial or verified account) within the free limits.
  • Operation family: SEO
  • Scope: api:seo:read
  • Credits: 40 credits reserved on acceptance, for either group
  • Idempotency: Idempotency-Key header required

Request

curl -X POST https://www.chab.ai/v1/seo/domains/backlinks \
  -H "Authorization: Bearer CHAB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: domain-backlinks-001" \
  -d '{"domain":"example.com","include_subdomains":false,"limit":100,"filters":{"status":"live","link_attribute":"all"},"sort":"authority_desc"}'

{
  "domain": "example.com",
  "include_subdomains": false,
  "limit": 100,
  "filters": {
    "status": "live",
    "link_attribute": "all"
  },
  "sort": "authority_desc"
}

Fields:

  • domain, include_subdomains, path_scope, location.country, language, and callback fields match the overview endpoint.
  • group: optional backlinks or referring_domains; defaults to backlinks. See Referring domains.
  • limit: optional integer from 1 to 1000; defaults to 100.
  • filters.status: optional live, lost, or all; defaults to live.
  • filters.link_attribute: optional follow, nofollow, or all; defaults to all.
  • filters.target_path_prefix: optional path beginning with /. When path_scope is set, this prefix must be equal to or inside path_scope.
  • sort: optional authority_desc, first_seen_desc, last_seen_desc, or source_url_asc; defaults to authority_desc. With group: "referring_domains" the orders are authority_desc, backlinks_desc, and first_seen_desc.
  • output_format: optional Scale-only csv or json. It replaces the automatic backlinks JSONL artifact with one complete protected export. CSV is UTF-8 RFC 4180 with CRLF rows and spreadsheet-formula protection. JSON is one schema-versioned object rather than JSONL. The fixed operation price is unchanged; artifact download egress is still metered.

Unknown fields and unsupported output-mode fields such as artifact_format are rejected.

Result

The result contains a summary, at most 25 inline backlink sample rows, optional inline referring-domain rows, and an exports array when artifacts were created.

{
  "data": {
    "result": {
      "domain": "example.com",
      "include_subdomains": false,
      "path_scope": null,
      "location": null,
      "language": null,
      "fetched_at": "2026-06-29T12:00:05+00:00",
      "filters": {
        "status": "live",
        "link_attribute": "all",
        "target_path_prefix": null
      },
      "sort": "authority_desc",
      "summary": {
        "backlinks_total": 120,
        "referring_domains_total": 38,
        "live": 120,
        "lost": null,
        "follow": null,
        "nofollow": null
      },
      "sample": [
        {
          "source_url": "https://referrer.example/article",
          "source_domain": "referrer.example",
          "target_url": "https://example.com/docs",
          "target_path": "/docs",
          "anchor": "Example docs",
          "link_type": "follow",
          "rel": [],
          "first_seen": "2025-01-01T00:00:00+00:00",
          "last_seen": "2026-06-20T00:00:00+00:00",
          "status": "live",
          "redirect": false,
          "authority": {
            "score": 64
          },
          "language": null,
          "location": null,
          "availability": {
            "source_url": "available",
            "source_domain": "available",
            "target_url": "available",
            "target_path": "available",
            "anchor": "available",
            "link_type": "available",
            "rel": "available",
            "first_seen": "available",
            "last_seen": "available",
            "authority.score": "available"
          },
          "confidence": {
            "score": 1,
            "availability": "available",
            "source": "chab"
          },
          "warnings": []
        }
      ],
      "exports": [
        {
          "role": "backlinks_export",
          "filename": "seo-domains-backlinks-op_01JZ7H0A1B2C3D4E5F6G7H8J9K.jsonl",
          "row_count": 120
        },
        {
          "role": "referring_domains_export",
          "filename": "seo-domains-referring-domains-op_01JZ7H0A1B2C3D4E5F6G7H8J9K.jsonl",
          "row_count": 38
        }
      ],
      "availability": {
        "summary.backlinks_total": "available",
        "summary.referring_domains_total": "available"
      },
      "complete": true
    },
    "artifacts": [
      {
        "id": "art_01JZ7H0A1B2C3D4E5F6G7H8J9K",
        "type": "jsonl",
        "role": "backlinks_export",
        "mime_type": "application/jsonl",
        "byte_size": 2048,
        "checksum": "sha256:abc123",
        "filename": "seo-domains-backlinks-op_01JZ7H0A1B2C3D4E5F6G7H8J9K.jsonl",
        "metadata_url": "/v1/operations/op_01JZ7H0A1B2C3D4E5F6G7H8J9K/artifacts/art_01JZ7H0A1B2C3D4E5F6G7H8J9K",
        "download_url": "/v1/operations/op_01JZ7H0A1B2C3D4E5F6G7H8J9K/artifacts/art_01JZ7H0A1B2C3D4E5F6G7H8J9K/download",
        "expires_at": "2026-07-02T12:00:05+00:00"
      },
      {
        "id": "art_01JZ7H0A1B2C3D4E5F6G7H8J9M",
        "type": "jsonl",
        "role": "referring_domains_export",
        "mime_type": "application/jsonl",
        "byte_size": 1024,
        "checksum": "sha256:def456",
        "filename": "seo-domains-referring-domains-op_01JZ7H0A1B2C3D4E5F6G7H8J9K.jsonl",
        "metadata_url": "/v1/operations/op_01JZ7H0A1B2C3D4E5F6G7H8J9K/artifacts/art_01JZ7H0A1B2C3D4E5F6G7H8J9M",
        "download_url": "/v1/operations/op_01JZ7H0A1B2C3D4E5F6G7H8J9K/artifacts/art_01JZ7H0A1B2C3D4E5F6G7H8J9M/download",
        "expires_at": "2026-07-02T12:00:05+00:00"
      }
    ],
    "warnings": [],
    "result_expires_at": "2026-07-02T12:00:05+00:00"
  },
  "meta": {
    "request_id": "req_123"
  }
}

JSONL exports contain one normalized row per line. Download artifact URLs are ownership-checked, expire with the operation result retention window, and are retained for about 72 hours by default. Chab-streamed artifact downloads may create a separate egress charge in addition to the fixed operation price. Backlink and referring-domain rows include per-field availability maps and field_unavailable warnings for missing row-level data such as URLs, target paths, anchors, link type, rel attributes, observed timestamps, counts, and authority.

The summary split counts (live, lost, follow, and nofollow) are populated only when filters.status or filters.link_attribute selects that single slice; when either is all, the corresponding counts are null because the split is not computed. backlinks_total and referring_domains_total always reflect the full matched set.

If the operation fetches fewer rows than the reported total, complete is false and the response includes a result_truncated warning. Export row_count values report the rows exported by Chab; totals remain in summary.

Referring domains

Send group: "referring_domains" for one row per linking domain, for example the top 100 domains that link to a site:

curl -X POST https://www.chab.ai/v1/seo/domains/backlinks \
  -H "Authorization: Bearer CHAB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: domain-referring-domains-001" \
  -d '{"domain":"example.com","group":"referring_domains","limit":100,"sort":"authority_desc"}'

filters.status, filters.link_attribute and filters.target_path_prefix choose which links count. Every row up to limit comes back inline in referring_domains, with its backlink count, referring pages, follow and nofollow page counts, first-seen date, authority score (0 to 100) and spam score (0 to 100).

authority.score is the linking site's own strength (its domain rank scaled to 0 to 100), so github.com scores high whatever page it links from. With sort: "authority_desc", the default, Chab takes the 1,000 linking domains with the most linking pages, ranks them by their own authority and returns the strongest limit. The other orders return the first limit domains by backlinks or first-seen date, each with its own authority. If the authority check is unavailable, the rows keep the linking-pages order, authority.score is null, and a provider_degraded warning says so. On Scale, output_format adds a complete CSV or JSON file with role referring_domains_bulk_export.

{
  "domain": "example.com",
  "include_subdomains": false,
  "path_scope": null,
  "location": null,
  "language": null,
  "fetched_at": "2026-11-12T12:00:05+00:00",
  "group": "referring_domains",
  "filters": {
    "status": "live",
    "link_attribute": "all",
    "target_path_prefix": null
  },
  "sort": "authority_desc",
  "summary": {
    "referring_domains_total": 38,
    "returned": 1
  },
  "referring_domains": [
    {
      "domain": "referrer.example",
      "backlinks": 12,
      "referring_pages": 9,
      "dofollow": 10,
      "nofollow": 2,
      "first_seen": "2025-01-01T00:00:00+00:00",
      "last_seen": null,
      "authority": {
        "score": 64
      },
      "spam_score": 3,
      "availability": {
        "domain": "available",
        "backlinks": "available",
        "last_seen": "unavailable"
      },
      "warnings": []
    }
  ],
  "exports": [],
  "complete": false
}

POST/v1/seo/domains/keywords

Lists the Google keywords a domain ranks for in organic results: the position, the page that ranks, monthly search volume, cost per click, keyword difficulty and estimated monthly visits from each keyword, plus totals for the whole domain.

Required Access

  • Access: Paid plans that include this family, or free credits (guest trial or verified account) within the free limits.
  • Operation family: SEO
  • Scope: api:seo:read
  • Credits: 4 per request plus 4 per started 100 keywords: 8 credits for the default 100 keywords, 44 credits for 1,000
  • Idempotency: Idempotency-Key header required

Request

curl -X POST https://www.chab.ai/v1/seo/domains/keywords \
  -H "Authorization: Bearer CHAB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: domain-keywords-001" \
  -d '{"domain":"example.com","location":{"country":"US"},"language":"en","limit":100,"order":"traffic_desc"}'

Fields:

  • domain: required hostname or HTTPS URL, normalized to the registrable domain. Rankings include its subdomains. An HTTPS URL path becomes path_scope.
  • path_scope: optional path such as /blog. Only keywords whose ranking URL starts with this path are listed.
  • location.country: optional ISO 3166-1 alpha-2 country code for the Google market. Omit it for every country combined. See Ranking markets.
  • language: optional language of the market, such as en or de. Omit it for every language in the market. It needs location.country.
  • limit: optional integer from 1 to 1000; defaults to 100.
  • order: optional traffic_desc (most estimated visits first, the default), volume_desc (most searched first) or position_asc (best position first).
  • Callback fields match the overview endpoint.

Result

{
  "domain": "example.com",
  "path_scope": null,
  "location": {
    "country": "US"
  },
  "language": "en",
  "fetched_at": "2026-11-12T12:00:05+00:00",
  "order": "traffic_desc",
  "currency": "USD",
  "totals": {
    "ranked_keywords": 4210,
    "returned": 2,
    "estimated_traffic": 18450,
    "top_3": 96,
    "top_10": 412,
    "returned_estimated_traffic": 3790,
    "returned_search_volume": 14000
  },
  "keywords": [
    {
      "keyword": "example api",
      "position": 1,
      "url": "https://example.com/api",
      "search_volume": 8100,
      "cpc": 4.12,
      "keyword_difficulty": 38,
      "estimated_traffic": 2560.5,
      "search_intent": "navigational",
      "country": "US",
      "language": "en"
    },
    {
      "keyword": "example pricing",
      "position": 2,
      "url": "https://example.com/pricing",
      "search_volume": 5900,
      "cpc": 6.3,
      "keyword_difficulty": 41,
      "estimated_traffic": 1229.6,
      "search_intent": "commercial",
      "country": "US",
      "language": "en"
    }
  ],
  "complete": false
}

totals.ranked_keywords, estimated_traffic, top_3 and top_10 describe every keyword the domain ranks for in the market; the returned_ totals add up the listed rows. Each row names its market in country and language; without location the same keyword can appear once per market. cpc is in currency. keyword_difficulty runs from 0 to 100. Any value the data does not have is null. When the domain ranks for more keywords than limit, complete is false with a result_truncated warning.

POST/v1/seo/domains/traffic

Estimates the monthly organic Google visits of a domain, the number of keywords it ranks for and how many rank in the top 3 and top 10, plus one row per month for up to 24 months, ready to chart.

Required Access

  • Access: Paid plans that include this family, or free credits (guest trial or verified account) within the free limits.
  • Operation family: SEO
  • Scope: api:seo:read
  • Credits: 55 credits reserved on acceptance, for 1 to 24 months
  • Idempotency: Idempotency-Key header required

Request

curl -X POST https://www.chab.ai/v1/seo/domains/traffic \
  -H "Authorization: Bearer CHAB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: domain-traffic-001" \
  -d '{"domain":"example.com","location":{"country":"US"},"months":12}'

Fields:

  • domain: required hostname or HTTPS URL without a path, normalized to the registrable domain. Traffic includes its subdomains.
  • location.country: optional Google market, US when omitted. See Ranking markets.
  • language: optional language of the market; the country's main language when omitted. The result echoes the market used.
  • months: optional integer from 1 to 24; defaults to 12.
  • Callback fields match the overview endpoint.

Result

{
  "domain": "example.com",
  "location": {
    "country": "US"
  },
  "language": null,
  "fetched_at": "2026-11-12T12:00:05+00:00",
  "currency": "USD",
  "current": {
    "organic_traffic": 18450,
    "organic_keywords": 4210,
    "top_3": 96,
    "top_10": 412,
    "organic_traffic_value": 33210.4,
    "paid_traffic": 0,
    "paid_keywords": 0
  },
  "history": [
    {
      "month": "2026-09",
      "organic_traffic": 17320,
      "organic_keywords": 4050,
      "top_3": 81,
      "top_10": 405,
      "organic_traffic_value": 31176,
      "paid_traffic": 0,
      "paid_keywords": 0
    },
    {
      "month": "2026-10",
      "organic_traffic": 18450,
      "organic_keywords": 4210,
      "top_3": 84,
      "top_10": 421,
      "organic_traffic_value": 33210,
      "paid_traffic": 0,
      "paid_keywords": 0
    }
  ],
  "availability": {
    "current": "available",
    "history": "available"
  },
  "complete": true
}

organic_traffic is the estimated monthly visits from organic Google results and organic_traffic_value what those visits would cost as ads, in currency. top_10 includes top_3. history is oldest month first and ends with the latest monthly snapshot, which can be the running month. When fewer months exist than requested, complete is false with a field_unavailable warning. A domain without rankings in the market returns null metrics with current marked unavailable.

Ranking markets

Ranked keywords, traffic and the overview's organic visibility come from Google ranking data, which covers these countries and languages (the first one is the default): AE ar, en; AR es; AT de; AU en; BE nl, fr, de; BR pt; CA en, fr; CH de, fr, it; CL es; CO es; DE de; DK da; ES es; FI fi; FR fr; GB en; HK zh-TW, en; ID id, en; IE en; IN en, hi; IT it; JP ja; KR ko; MX es; MY en, ms; NL nl; NO nb; NZ en; PH en, tl; PL pl; PT pt; SE sv; SG en, zh-CN; TH th; TR tr; US en, es; ZA en. Regional tags such as de-DE or en-GB are accepted and reduced to the market language. Another country or language is rejected with validation_failed and the list of options, before any credits are reserved.

Errors

Common errors include validation_failed, api_scope_missing, paid_plan_required, operation_family_not_included, insufficient_credits, provider_unavailable, provider_temporarily_rate_limited, rate_limited, and the shared idempotency errors.

Credit Notes

Domain overview costs 35 credits. Domain backlinks costs 40 credits for the documented request caps, with either group. Ranked keywords cost 4 credits per request plus 4 per started 100 keywords (8 for 100, 44 for 1,000). Search traffic costs 55 credits for 1 to 24 months. Artifact download egress is metered separately when Chab streams bytes.