V2 Links
What's Covered?
In this guide you’ll learn more about making API calls to the Links 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 get a list of links to a target. In other words, this endpoint returns a list of links pointing to your site or page. This endpoint will return URL Metrics for both the source and the target. You can specify filters and the scope for the data returned - for example, you can request a list of pages linking to your target that are follow links. This can help you during backlink audits and link building alike. The data from this endpoint is similar to the data seen in the Inbound Links section of Link Explorer.
On This Page
Getting Started
Before making calls to the Links 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 links data from Links V2, be sure to use the following endpoint.
https://lsapi.seomoz.com/v2/links
Request Syntax
{
"target": "string",
"target_scope": "string",
"sort": "string",
"filter": "string",
"anchor_text: "string",
"source_root_domain": "string",
"source_scope": "string",
"subdomains_limited_to_one": ["string"],
"limit": number,
"next_token": "string
}
Example JSON Request
{
"target": "moz.com/blog",
"target_scope": "page",
"filter": "external+nofollow",
"limit": 1
}
Request Parameters
"target" - A URL to get links for.
- Type: string
- Required: yes
"target_scope" - Find links to 'target' at this scope. The default value is 'page'.
- Type: string
- Required: no
- Valid Values: page, subdomain, root_domain
"sort" - The order to return links in. The default value is 'source_page_authority'. Results are returned in descending order (higher values first).
- Type: string
- Required: no
- Valid Values: See the Parameter Compatibility section below.
"filter"- Only return links that match this filter. The default value is 'external'. Multiple filters can be combined into an expression using the '+' symbol (for example, 'external+follow').
- Type: string
- Required: no
- Valid Values: See the Parameter Compatibility section below.
"anchor_text" - If set, returns only links whose anchor text matches the specified value after normalization. The steps used for normalization are: strip HTML tags, remove leading and trailing whitespace, replace whitespace between words with a single space, and drop all letters to lowercase. To request links with no anchor text, set this parameter to a single null character ("\u0000").
- Type: string
- Required: no
"source_root_domain" - If set, returns only links from a specific source root domain to the target.
- Type: string
- Required: no
"source_scope" - If set to 'subdomain' or 'root_domain', return only the best link from each source at that scope, as ordered by the 'sort' parameter. The default value is 'page'.
- Type: string
- Required: no
- Valid Values: page, subdomain, root_domain
"subdomains_limited_to_one" - If set, only return the best link from each of the subdomains specified, as ordered by the 'sort' parameter.
- Type: Array of string objects
- 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
Parameter Compatibility
The following combinations of request parameters are valid:
at* = anchor_text
srd* = source_root_domain
slto* = subdomains_limited_to_one
| at* | srd* | slto* | sort | filter |
|---|---|---|---|---|
| unset | unset | unset | unsorted | all |
| unset | unset | either | root_domains_to_source_root_domain, root_domains_to_source_page, source_page_authority, source_domain_authority, source_link_propensity, source_spam_score | external, external + [ follow | nofollow | deleted | not_deleted | redirect | not_redirect | rel_canonical | not_rel_canonical | via_redirect | not_via_redirect | via_rel_canonical | not_via_rel_canonical ] |
| set | unset | either | source_page_authority, source_domain_authority, source_link_propensity, source_spam_score | external, external + [ follow | nofollow | deleted | not_deleted | redirect | not_redirect | rel_canonical | not_rel_canonical | via_redirect | not_via_redirect | via_rel_canonical | not_via_rel_canonical ] |
| unset | set | either | source_page_authority | external, external + [ follow | nofollow | deleted | not_deleted | gained_last_60_days | lost_last_60_days ] |
Response Syntax
{
"results": [{
"source": UrlMetricsResponse,
"target": UrlMetricsResponse,
"anchor_text": "string",
"date_first_seen": "string",
"date_last_seen": "string",
"date_disappeared": "string",
"nofollow": boolean,
"redirect": boolean,
"rel_canonical": boolean,
"via_redirect": boolean,
"via_rel_canonical": boolean
}],
"next_token": "string"
}
Example JSON Response
{
"results": [
{
"source": {
"page": "github.com/mezod/awesome-indie",
"subdomain": "github.com",
"root_domain": "github.com",
"title": "GitHub - mezod/awesome-indie: Resources for independent developers to make money",
"last_crawled": "2021-03-27",
"http_code": 200,
"pages_to_page": 1299,
"nofollow_pages_to_page": 791,
"redirect_pages_to_page": 20,
"external_pages_to_page": 1275,
"external_nofollow_pages_to_page": 791,
"external_redirect_pages_to_page": 20,
"deleted_pages_to_page": 1092,
"root_domains_to_page": 148,
"indirect_root_domains_to_page": 3,
"deleted_root_domains_to_page": 28,
"nofollow_root_domains_to_page": 27,
"pages_to_subdomain": 3496581036,
"nofollow_pages_to_subdomain": 393229690,
"redirect_pages_to_subdomain": 79405409,
"external_pages_to_subdomain": 3280155224,
"external_nofollow_pages_to_subdomain": 386397939,
"external_redirect_pages_to_subdomain": 78878408,
"deleted_pages_to_subdomain": 1258410538,
"root_domains_to_subdomain": 2025650,
"deleted_root_domains_to_subdomain": 288876,
"nofollow_root_domains_to_subdomain": 132981,
"pages_to_root_domain": 3677205830,
"nofollow_pages_to_root_domain": 411480625,
"redirect_pages_to_root_domain": 80842865,
"external_pages_to_root_domain": 3423407132,
"external_indirect_pages_to_root_domain": 644616810,
"external_nofollow_pages_to_root_domain": 404171837,
"external_redirect_pages_to_root_domain": 79191179,
"deleted_pages_to_root_domain": 1313389459,
"root_domains_to_root_domain": 2111561,
"indirect_root_domains_to_root_domain": 144214,
"deleted_root_domains_to_root_domain": 296948,
"nofollow_root_domains_to_root_domain": 146172,
"page_authority": 65,
"domain_authority": 96,
"link_propensity": 0.09559579194,
"spam_score": 2,
"root_domains_from_page": 95,
"nofollow_root_domains_from_page": 90,
"pages_from_page": 193,
"nofollow_pages_from_page": 188,
"root_domains_from_root_domain": 564071,
"nofollow_root_domains_from_root_domain": 433232,
"pages_from_root_domain": 6743328,
"nofollow_pages_from_root_domain": 4967074,
"pages_crawled_from_root_domain": 5900584
},
"target": {
"page": "moz.com/blog",
"subdomain": "moz.com",
"root_domain": "moz.com",
"title": "Moz Blog - SEO and Inbound Marketing Blog - Moz",
"last_crawled": "2021-03-28",
"http_code": 200,
"pages_to_page": 690934,
"nofollow_pages_to_page": 5762,
"redirect_pages_to_page": 964,
"external_pages_to_page": 531315,
"external_nofollow_pages_to_page": 5762,
"external_redirect_pages_to_page": 345,
"deleted_pages_to_page": 24210,
"root_domains_to_page": 7418,
"indirect_root_domains_to_page": 2005,
"deleted_root_domains_to_page": 1289,
"nofollow_root_domains_to_page": 1235,
"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": 67,
"domain_authority": 91,
"link_propensity": 0.009834184311,
"spam_score": 3,
"root_domains_from_page": 5,
"nofollow_root_domains_from_page": 0,
"pages_from_page": 5,
"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
},
"anchor_text": "moz blog",
"date_first_seen": "2020-06-29",
"date_last_seen": "2021-03-27",
"date_disappeared": "",
"nofollow": true,
"redirect": false,
"rel_canonical": false,
"via_redirect": false,
"via_rel_canonical": false
}
],
"next_token": "AdfN8uHYSlbr"
}
Response Elements
"results" - An array of links to 'target'.
- Type: Array of Map objects
- Within “results” the following response elements exist:
- "source" - Url metrics for the source of the link.
- Type: UrlMetricsResponse, which has the same format as each item in the 'results' array returned by the 'url_metrics' endpoint.
- "target" - Url metrics for the target of the link.
- Type: UrlMetricsResponse, which has the same format as each item in the 'results' array returned by the 'url_metrics' endpoint.
- "anchor_text" - The anchor text associated with this link.
- Type: string
- "date_first_seen" - The date this link was first seen, in 'YYYY-MM-DD' format.
- Type: string
- "date_last_seen" - The date this link was most recently seen, in 'YYYY-MM-DD' format.
- Type: string
- "date_disappeared" - The date this link most recently disappeared (changed from being present to absent on its source page), in 'YYYY-MM-DD' format.
- Type: string
- "nofollow"- Whether or not this link is a nofollow link.
- Type: boolean
- "redirect" - Whether or not this link is a redirect.
- Type: boolean
- "rel_canonical" - Whether or not this link is a rel-canonical link.
- Type: boolean
- "via_redirect" - Whether or not this link is an indirect link via a redirecting page.
- Type: boolean
- "via_rel_canonical" - Whether or not this link is an indirect link via a rel-canonical tag.
- Type: boolean
- "source" - Url metrics for the source of the link.
"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
Limits
- 100,000 links, if 'anchor_text' and 'source_root_domain' are not set
- 500 links, if 'anchor_text' is set
- 10 links, if 'source_root_domain' is set, and 'filter' is 'external'. Non-deleted links are given preference over deleted links if both exist.
- 1 link, if 'source_root_domain' is set, and 'filter' includes 'gained_last_60_days' or 'lost_last_60_days'
Errors
See the Common Errors section for errors that are common to all endpoints.
'Gone'
Message: The next token has expired
HTTP Status code: 410
Example HTTP Request
POST /v2/links
Host: lsapi.seomoz.com
Content-Length: [length of request payload in bytes]
User-Agent: [user agent string]
Authorization: Basic [credentials]
{
"target": "moz.com/blog",
"target_scope": "page",
"filter": "external+nofollow",
"limit": 1
}
Example cURL Request
curl -d '{"target": "moz.com/blog", "target_scope": "page", "filter": "external+nofollow", "limit": 1}' -X POST https://lsapi.seomoz.com/v2/links -u 'access_id:secret_key'
Example Python Request
import requests
auth = (access_id, secret_key)
url = "https://lsapi.seomoz.com/v2/links"
data = """{
"target": "moz.com/blog",
"target_scope": "page",
"filter": "external+nofollow",
"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.