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 documentation specifies information for Moz Links 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)
Related Articles
Was this article helpful?
Yes! Amazing!
Yes! It was what I needed.
Meh. It wasn’t really what I was looking for.
No, it wasn’t helpful at all.
Thanks for the feedback.