Top Pages

What's Covered?

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

This endpoint returns top pages on a target domain.

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

Quick Links

Getting Started

Before making calls to the Top Pages endpoint, be sure you are set up with an Access ID and Secret Key within your Moz Account.

Just a reminder - the Links API V2 supports Basic Auth in which you are able to use your Access ID as a username and and your Secret Key as a password.

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)
        

Woo! 🎉
Thanks for the feedback.

Got it.
Thanks for the feedback.