1. Help
  2. Moz API
  3. V2 API Endpoint Documentation
  4. V2 Top Pages

V2 Top Pages

Have you heard? We've launched a brand new set of Moz API endpoints, including Keyword Suggestions, Search intent, Brand AuthorityTM, and more! To learn more and get started, check out the all-new documentation here.

What's Covered?

In this guide you’ll learn more about making API calls to the Top Pages endpoint for the Moz API V2.

This documentation specifies information for Moz API V2. V1 documentation is available here.

What is this endpoint for?

Use this endpoint to return a list of the top pages on a target domain. Top pages are identified as the pages on a site with the most external links. The default sort for this endpoint is by descending Page Authority however, you can also sort by descending linking domains or inbound links. By applying filters to your query, the API can return a list of broken pages (returning a 4xx status code) with links. You can also use this data for link acquisition research and competitive analysis. The data from this endpoint is similar to the data in the Top Pages section of Link Explorer.

Quick Links

Getting Started

Before making calls to the Top Pages endpoint, be sure you are set up with an API token within your Moz Account.

For information regarding authentication, please see our Overview & Authentication guide.

All requests and responses are structured in JSON.

Endpoint Location

When requesting top pages data from Links V2, be sure to use the following endpoint.

          
https://lsapi.seomoz.com/v2/top_pages

Request Syntax

          
{
    "target": "string",
    "scope": "string",
    "sort": "string",
    "filter": "string",
    "daily_history_deltas": ["string"],
    "daily_history_values": ["string"],
    "monthly_history_deltas": ["string"],
    "monthly_history_values": ["string"],
    "limit": number,
    "next_token": "string"
}

Example JSON Request

          
{
    "target": "moz.com",
    "scope": "root_domain",
    "limit": 1
}

Request Parameters

"target" - The domain to return top pages for.

  • Type: string
  • Required: yes

"scope" - The scope to find top pages on 'target' at. The default value is 'root_domain'.

  • Type: string
  • Required: no
  • Valid Values: subdomain, root_domain

"sort" - The order to return results in. Results are returned in descending order (higher values first). The default value is 'page_authority'.

  • Type: string
  • Required: no
  • Valid Values: page_authority, root_domains_to_page, external_pages_to_page

"filter" - If set, only return results that match this filter. The valid values correspond to the http status code returned the most recent time a page was crawled. The default value is 'all'.

  • Type: string
  • Required: no
  • Valid Values: all, status_200, status_301, status_302, status_4xx, status_5xx

"daily_history_deltas"- This parameter has the same definition as it does in the 'Url Metrics' endpoint. If set, it applies to each result.

  • Required: no

"daily_history_values" - This parameter has the same definition as it does in the 'Url Metrics' endpoint. If set, it applies to each result.

  • Required: no

"monthly_history_deltas" - This parameter has the same definition as it does in the 'Url Metrics' endpoint. If set, it applies to each result.

  • Required: no

"monthly_history_values" - This parameter has the same definition as it does in the 'Url Metrics' endpoint. If set, it applies to each result.

  • Required: no

"limit" - Only return up to this number of results. The default value is 25.

  • Type: number
  • Required: no
  • Valid Values: 1-50

"next_token" - If set, return the next set of results from a previous request whose 'next_token' element equals this value.

  • Type: string
  • Required: no

Response Syntax

          
{
    "results": [UrlMetricsResponse],
    "next_token": "string"
}

Example JSON response

          
{
   "results": [
       {
           "page": "moz.com/",
           "subdomain": "moz.com",
           "root_domain": "moz.com",
           "title": "Moz - SEO Software for Smarter Marketing",
           "last_crawled": "2021-03-30",
           "http_code": 200,
           "pages_to_page": 15246482,
           "nofollow_pages_to_page": 10023551,
           "redirect_pages_to_page": 3640198,
           "external_pages_to_page": 15085290,
           "external_nofollow_pages_to_page": 10023551,
           "external_redirect_pages_to_page": 3639773,
           "deleted_pages_to_page": 1474443,
           "root_domains_to_page": 29655,
           "indirect_root_domains_to_page": 10027,
           "deleted_root_domains_to_page": 5382,
           "nofollow_root_domains_to_page": 5571,
           "pages_to_subdomain": 59964114,
           "nofollow_pages_to_subdomain": 19606689,
           "redirect_pages_to_subdomain": 19207735,
           "external_pages_to_subdomain": 40395969,
           "external_nofollow_pages_to_subdomain": 19556717,
           "external_redirect_pages_to_subdomain": 13073680,
           "deleted_pages_to_subdomain": 21013500,
           "root_domains_to_subdomain": 133072,
           "deleted_root_domains_to_subdomain": 23289,
           "nofollow_root_domains_to_subdomain": 26715,
           "pages_to_root_domain": 61070607,
           "nofollow_pages_to_root_domain": 19682997,
           "redirect_pages_to_root_domain": 19211678,
           "external_pages_to_root_domain": 40562873,
           "external_indirect_pages_to_root_domain": 20724873,
           "external_nofollow_pages_to_root_domain": 19632560,
           "external_redirect_pages_to_root_domain": 13076500,
           "deleted_pages_to_root_domain": 21083773,
           "root_domains_to_root_domain": 133693,
           "indirect_root_domains_to_root_domain": 26483,
           "deleted_root_domains_to_root_domain": 23442,
           "nofollow_root_domains_to_root_domain": 26794,
           "page_authority": 72,
           "domain_authority": 91,
           "link_propensity": 0.009834184311,
           "spam_score": 3,
           "root_domains_from_page": 1,
           "nofollow_root_domains_from_page": 0,
           "pages_from_page": 1,
           "nofollow_pages_from_page": 0,
           "root_domains_from_root_domain": 67837,
           "nofollow_root_domains_from_root_domain": 55026,
           "pages_from_root_domain": 328690,
           "nofollow_pages_from_root_domain": 197495,
           "pages_crawled_from_root_domain": 6898081
       }
   ],
   "next_token": "AX7y1ieXn2Rh"
}

Response Elements

"results" - An array of top pages on 'target'.

  • Type: Array of UrlMetricsResponse objects, which have the same format as each item in the 'results' array returned by the 'url_metrics' endpoint.

"next_token" - If non-empty, the number of results was limited by the 'limit' parameter, and the next set of results can be obtained by repeating the request with the 'next_token' request parameter set to this value.

  • Type: string

Example HTTP Request

          
POST /v2/top_pages
Host: lsapi.seomoz.com
Content-Length: [length of request payload in bytes]
User-Agent: [user agent string]
Authorization: Basic [credentials]
{
    "target": "moz.com",
    "scope": "root_domain",
    "limit": 1
}

Example cURL Request

          
curl -d '{"target": "moz.com", "scope": "root_domain", "limit": 1}' -X POST https://lsapi.seomoz.com/v2/top_pages -u 'access_id:secret_key'

Example Python Request

          
import requests
auth = (access_id, secret_key)
url = "https://lsapi.seomoz.com/v2/top_pages"
data = """{
        "target": "moz.com",
        "scope": "root_domain",
        "limit": 5
    }"""
request = requests.post(url, data=data, auth=auth)

Was this article helpful?

Thanks for the feedback.

Contact the Help Team if you have a specific question.
Cancel

Woo! 🎉
Thanks for the feedback.

Got it.
Thanks for the feedback.