Moz API V2 Global Root Domains Endpoint Documentation – Help Hub – Moz

If you’ve ever looked at a competitor’s backlink profile and thought, “Cool… but who are the big kids on the playground?”
the Moz API V2 Global Root Domains endpoint is your shortcut to that answer. It’s the endpoint that returns the
top root domains across Moz’s link index, ranked by Domain Authoritya handy “global leaderboard” you can
use for benchmarking, competitive research, and building smarter SEO workflows.

This guide rewrites and expands the official documentation into a practical, copy-and-paste-friendly reference. You’ll learn what
the endpoint does, how to call it, how to handle pagination and rate limits, and how to turn “a list of the internet’s biggest
domains” into something you can actually use without crying into your coffee.

What the Global Root Domains Endpoint Does (and Why You’d Use It)

The Global Root Domains endpoint returns the top 500 root domains in Moz’s index with the highest
Domain Authority (DA), sorted in descending order. Think of it as a “Top 500 domains” chartexcept instead of pop
songs, it’s sites that are generally strong in terms of authority signals and link equity.

What Moz Means by “Root Domain”

In practical SEO terms, a root domain typically refers to the registrable domain (often “apex domain”), such as
example.com. Subdomains (like blog.example.com) roll up to that root domain. When you’re using the API,
treat “root domain” as the top-level domain entity used for Moz’s domain-level calculations and aggregation.

Common Use Cases

• Benchmarking: Compare your domain’s DA distribution against the “global top” list to calibrate expectations.
• Prospecting & outreach strategy: Use the top domains list as a reference set to understand what “high authority”
  looks like in your vertical (then refine by nichebecause pitching a global social network for your local bakery is… ambitious).
• Competitive intelligence: Combine the global list with other endpoints (like linking root domains or link intersect)
  to spot patterns in who links to leaders and how authority clusters.
• SEO reporting dashboards: Power a “market context” panel in client reports: “Here’s where you sit relative to the web’s
  top domains.”

Endpoint Overview

Base URL

Moz Links API V2 endpoints use the base URL:

Global Root Domains Endpoint

The endpoint path is:

The request is typically a POST with a JSON body. Responses are JSON.

Authentication and Headers

Moz provides a token-based approach where you pass your token in a request header. In practice, you may also see
Basic Auth examples in tooling and sample code, depending on how your Moz credentials are represented.
Either way, treat credentials like you’d treat your house keys: don’t leave them under the doormat (or in a public repo).

Header-Based Token (Common Pattern)

Basic Auth (Seen in Some Examples)

Some implementations authenticate using HTTP Basic Auth where the “username” is your access ID and the “password” is your secret key.
Many HTTP clients can set this automatically for you (for example, a requests library auth tuple or Postman’s Basic Auth UI).

Request Body

The Global Root Domains endpoint is designed to be simple. You generally specify how many results you want back per call,
then use pagination tokens (if provided) to move through the list.

Typical Parameters

• limit (number): How many root domains to return in the response (up to the endpoint’s maximum; the endpoint
  is described as returning up to 500 top root domains).
• next_token (string, optional): A token from a previous response used to fetch the next page of results.

Example Request Body

If you’re paginating, the next request would include the token:

Response Format (What You’ll Get Back)

Responses are JSON. For most Moz V2 Links API endpoints, you should expect:

• results: An array of result objects
• next_token: A pagination token if more results are available
• rows_consumed: How many “rows” your request consumed for billing/quota purposes

For Global Root Domains specifically, each result object commonly includes the root domain and the authority metric that powers the ranking.
Treat the example below as an illustrative shape (field names may vary slightly by version and plan).

Illustrative Response Shape

Practical Examples

1) cURL Example (Token Header)

2) Python Example (requests)

This example uses a token header. If you use Basic Auth in your environment, you can swap headers for auth=(access_id, secret_key).

3) JavaScript Example (fetch)

Pagination: Pulling the Full Top 500 (Without Making Your API Cry)

Since this endpoint is described as returning the top 500 root domains, you might be able to retrieve everything in one shot if your
plan and the endpoint’s maximum limit allow it. If not, paginate in sensible chunks (25, 50, or 100), and keep going until
next_token disappears.

A Simple Pagination Loop (Pseudo-Logic)

1. Request page 1 with {"limit": 50}
2. Store results
3. If next_token exists, request again with {"limit": 50, "next_token": "..."}
4. Stop when no token is returned

Rate Limits and Error Handling

APIs are like highways: if everyone floors it at once, someone gets pulled over. The Moz API can return standard HTTP error codes,
and the cheat sheet highlights common ones like 400 (bad request), 401 (not authorized),
403 (forbidden), and 429 (too many requests / plan limits).

How to Handle 429 Like a Pro

• Respect Retry-After: If the response includes a Retry-After header, wait that long before retrying.
• Use exponential backoff: Wait 1s, then 2s, then 4s, etc. This reduces “thundering herd” behavior and increases success rates.
• Cache aggressively: The top 500 root domains list doesn’t need minute-by-minute refreshing for most reporting.
  Pull it daily or weekly unless you have a very specific reason not to.

Common “Oops” Errors (and Quick Fixes)

• 400 Bad Request: Usually malformed JSON, wrong parameter types, or an invalid value. Validate your JSON and keep parameter names exact.
• 401 Not Authorized: Token missing/expired/invalid. Double-check the header key, token value, and environment variable injection.
• 403 Forbidden: Can indicate banned access or an unrecognized method/endpoint. Confirm the endpoint path and your plan status.
• ASCII-only URL complaints: If you’re mixing other endpoints into your workflow, you may need to normalize or encode internationalized domains (IDNs).

Turning the Endpoint Into Real SEO Work

A “Top 500 domains” list is cool trivia… but trivia doesn’t pay the bills. Here are a few concrete ways to turn this endpoint into
something actionable.

Workflow 1: Build a Global Authority Benchmark Chart

1. Fetch the top 500 root domains and their DA.
2. Compute percentiles (median, 75th, 90th, etc.).
3. Plot your client’s DA against those percentiles.
4. Explain it in plain English: “You’re at the 70th percentile relative to the web’s most authoritative domains.”
   (Yes, it’s a little apples-to-orchards. But stakeholders love a good orchard.)

Workflow 2: Identify “Authority Neighborhoods” by Niche

The global list will include many household names. To make it niche-relevant, enrich the list with additional metadata:

• Pull your own categorization layer (industry tags, topic clusters, knowledge graph categories).
• Group the “top domains” by category.
• Use the results to set realistic link-building targets and to understand how competitive the SERP landscape is.

Workflow 3: Combine With Link Intersect for Competitive Gaps

The Global Root Domains endpoint is a great seed for “who matters on the web.” Pair it with endpoints like Link Intersect to find
domains that link to competitors but not to you, then prioritize outreach targets that are both relevant and authoritative.
(Relevance first, thoughno one wants a high-DA link that screams “totally unrelated.”)

Usage, Rows Consumed, and Staying on Budget

Moz’s API pricing/usage is commonly based on “rows” returned, where a row is a JSON object (like a link, a domain metrics item,
or an anchor text object), and some endpoints are weighted depending on what you request. That means smart limits, smart caching,
and not calling endpoints in a tight loop like a caffeinated woodpecker can save real money.

If you want to monitor consumption programmatically, Moz provides a usage_data endpoint that can return rows consumed in a time window.
For many teams, the best pattern is: run your data pulls on a schedule, log rows_consumed per job, and alert if the usage curve
starts climbing like it’s training for a marathon.

Best Practices for Production Integrations

1) Treat Tokens Like Secrets

• Store credentials in environment variables or a secrets manager.
• Rotate tokens if you suspect exposure.
• Never embed tokens directly into client-side JavaScript.

2) Validate Inputs and Normalize Domains

Even though Global Root Domains is relatively simple, your overall Moz API integration likely touches domain inputs elsewhere.
Normalize domains (lowercase, trim spaces), handle IDNs carefully, and keep your JSON payloads strictly valid.

3) Be Nice to the API (and Your Future Self)

• Back off on 429s.
• Batch work where possible (fewer calls, smarter payloads).
• Cache results (especially global lists that don’t change second-to-second).
• Log request IDs, status codes, and payload sizes for troubleshooting.

4) Security and Governance

If you’re building internal tools, follow API security best practices: least privilege, secure storage, input validation,
and clear rate-limiting/queuing. These patterns reduce operational risk and prevent accidental “whoops, I burned the whole quota”
events that tend to happen right before an important client meeting.

Conclusion

The Moz API V2 Global Root Domains endpoint is the simplest kind of powerful: one call can give you a “global map” of
the web’s most authoritative root domains, sorted by Domain Authority. Use it to build benchmarks, feed competitive research,
power dashboards, and provide context your SEO reports usually lack. Pair it with thoughtful caching, polite retries, and
good security hygiene, and it becomes a dependable building block for real-world SEO automation.

Field Notes: of Real-World Experiences (What Teams Actually Run Into)

In real integrations, the “hard” part of Global Root Domains is rarely the endpoint itself. It’s everything around itthe small,
mundane details that either make your pipeline rock-solid or turn it into a nightly horror anthology.

First: expectations. Stakeholders often see “Top 500 domains” and assume it’s a ready-made prospect list. It isn’t. It’s a
context list. Many of the biggest domains are platforms, publishers, or properties you can’t realistically earn links from
through outreach (unless your outreach email is “Hello, I am the internet, please link to me,” whichbold). The best teams use
this endpoint as a reference baseline: “Here’s the ceiling,” then build niche filters and relevance layers on top.

Second: caching and refresh cadence. Because the output is global and relatively stable, a frequent mistake is over-refreshing.
If you pull the top 500 every hour “just in case,” you’ll spend quota for little gain. Teams that do this well schedule a refresh
(daily or weekly), store the dataset with a timestamp, and treat it like a snapshot. If they need “freshness,” they validate
index update timing using metadata endpoints, not by brute-forcing repeated calls.

Third: pagination surprises. Even when you request a high limit, you may still get paginated results depending on plan, internal
caps, or response size constraints. Robust integrations never assume “one call = done.” They loop until next_token is absent,
and they store progress so a failed job can resume rather than restart from page one. (Your future self will thank you, and may
even send you a fruit basket.)

Fourth: error handling is where “proof-of-concept” projects go to die. A common real-world scenario is hitting 429 errors during a
larger batch job (especially if you combine this endpoint with others). Teams that succeed build polite retry logic with exponential
backoff and pay attention to the Retry-After header when it appears. They also log error bodies because a 429 can mean
different thingsrate limiting, plan ceilings, or quota exhaustioneach requiring a different fix.

Finally: credential hygiene. The fastest way to ruin a good week is to accidentally commit a token to a repo, then spend the next
48 hours rotating secrets, auditing usage, and explaining to everyone why the dashboard looks like a hockey stick. The mature
pattern is boring (and that’s good): secrets manager, environment variables, least exposure, and clear internal guidelines.
Boring security is the kind that lets you sleep.