V2 Link Status

Frequently Asked Questions

  • This endpoint’s data will be counted as a 2x multiplier for each row returned by the Link Status endpoint. Please see here for more information on weighted endpoints.
Have you heard? We've launched a brand new set of Moz API beta 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 Link Status endpoint for the Moz API V2.

This documentation specifies information for Moz API V2. V1 of the Moz API does not include a Link Status endpoint.

What is this endpoint for?

Use this endpoint to get information about whether a link to a target from a particular source is included in our index. For example, you may make an API request to see if moz.com/blog (the target) has a link from twitter.com (the source). The endpoint will then return a response of true or false where true indicates the link is present and active in the index and false indicates there is no link from that source to the given target in the index. You can query multiple sources in one call, making it a great tool for monitoring link building campaigns for your own site or that of your competitors. This endpoint returns data similar to the Links to Target URL column in Link Tracking Lists within Link Explorer.

Please note: This is a weighted endpoint which means that data returned from this endpoint will count as more than 1 row consumed when data is requested. Please see here for more information on weighted endpoints.

Quick Links

Getting Started

Before making calls to the Link Status 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 link status data from Links V2, be sure to use the following endpoint.

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

Request Syntax

          
{
    "sources": ["string"],
    "target": "string",
    "source_scope": "string",
    "target_scope": "string"
}
        

Example JSON Request

          
{
    "target": "moz.com/blog",
    "sources": ["twitter.com", "linkedin.com"],
    "source_scope": "root_domain",
    "target_scope": "page"
}
        

Request Parameters

"sources" - Up to 50 sources to get information about.

  • Type: Array of string objects
  • Required: yes

"target" - Get information about links to this target.

  • Type: string
  • Required: yes

"target_scope" - Consider links to 'target' at this scope. The default value is 'page'.

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

"source_scope" - Consider links from each source at this scope. The default value is 'page'.

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

Response Syntax

          
{
    "exists": [boolean]
}
        

Example JSON Response

          
{
   "exists": [
       false,
       true
   ]
}
        

Response Elements

"exists" - An array of values aligning with request parameter 'sources', with each value indicating whether or not there is a link from that source to the target (given the requested source and target scopes).

  • Type: Array of boolean values

Limits

None (information about any link in the index can be queried, even if that link is not present in other endpoints)

Errors

See the Common Errors section for errors that are common to all endpoints.

Example HTTP Request

          
POST /v2/link_status
Host: lsapi.seomoz.com
Content-Length: [length of request payload in bytes]
User-Agent: [user agent string]
Authorization: Basic [credentials]
{
    "target": "moz.com/blog",
    "sources": ["google.com%2Finsights", "facebook.com"],
    "source_scope": "root_domain",
    "target_scope": "page"
}
        

Example cURL Request

          
curl -d '{"target": "moz.com/blog","sources": ["twitter.com", "linkedin.com"], "source_scope": "root_domain", "target_scope": "page"}' -X POST https://lsapi.seomoz.com/v2/link_status -u 'access_id:secret_key'
        

Example Python Request

          
import requests
auth = (access_id, secret_key)
url = "https://lsapi.seomoz.com/v2/link_status"
data = """{
      "target": "moz.com/blog",
        "sources": ["twitter.com", "linkedin.com"],
        "source_scope": "root_domain",
        "target_scope": "page"
    }"""
request = requests.post(url, data=data, auth=auth)
        

Woo! 🎉
Thanks for the feedback.

Got it.
Thanks for the feedback.