This endpoint will provide you with a list of backlinks and relevant data for the specified domain, subdomain, or webpage.
Note: API will return the list of unique backlinks from the referring pages;
if a page contains more than 1 backlink pointing to your target, the link with the highest rank will be returned; the number of duplicate backlinks from the referring page will be indicated in the links_count field.
Instead of ‘login’ and ‘password’ use your credentials from https://app.dataforseo.com/api-access
# Instead of 'login' and 'password' use your credentials from https://app.dataforseo.com/api-access \
login="login" \
password="password" \
cred="$(printf ${login}:${password} | base64)" \
curl --location --request POST "https://api.dataforseo.com/v3/backlinks/backlinks/live" \
--header "Authorization: Basic ${cred}" \
--header "Content-Type: application/json" \
--data-raw "[
{
"target": "forbes.com",
"mode": "as_is",
"filters": ["dofollow", "=", true],
"limit": 5
}
]"
<?php
// You can download this file from here https://cdn.dataforseo.com/v3/examples/php/php_RestClient.zip
require('RestClient.php');
$api_url = 'https://api.dataforseo.com/';
// Instead of 'login' and 'password' use your credentials from https://app.dataforseo.com/api-access
$client = new RestClient($api_url, null, 'login', 'password');
$post_array = array();
// simple way to set a task
$post_array[] = array(
"target" => "forbes.com",
"limit" => 5,
"mode" => "as_is",
"filters" => ["dofollow", "=", true]
);
try {
// POST /v3/backlinks/backlinks/live
$result = $client->post('/v3/backlinks/backlinks/live', $post_array);
print_r($result);
// do something with post result
} catch (RestClientException $e) {
echo "n";
print "HTTP code: {$e->getHttpCode()}n";
print "Error code: {$e->getCode()}n";
print "Message: {$e->getMessage()}n";
print $e->getTraceAsString();
echo "n";
}
$client = null;
?>
from client import RestClient
# You can download this file from here https://cdn.dataforseo.com/v3/examples/python/python_Client.zip
client = RestClient("login", "password")
post_data = dict()
# simple way to set a task
post_data[len(post_data)] = dict(
target="forbes.com",
limit=5,
mode="as_is",
filters=["dofollow", "=", True]
)
# POST /v3/backlinks/backlinks/live
response = client.post("/v3/backlinks/backlinks/live", post_data)
# you can find the full list of the response codes here https://docs.dataforseo.com/v3/appendix/errors
if response["status_code"] == 20000:
print(response)
# do something with result
else:
print("error. Code: %d Message: %s" % (response["status_code"], response["status_message"]))
using Newtonsoft.Json;
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
namespace DataForSeoDemos
{
public static partial class Demos
{
public static async Task backlinks_backlinks_live()
{
var httpClient = new HttpClient
{
BaseAddress = new Uri("https://api.dataforseo.com/"),
// Instead of 'login' and 'password' use your credentials from https://app.dataforseo.com/api-access
DefaultRequestHeaders = { Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password"))) }
};
var postData = new List<object>();
postData.Add(new
{
target = "forbes.com",
limit = 5,
mode = "as_is",
filters = new object[]
{
new object[] { "dofollow", "=", true }
}
});
// POST /v3/backlinks/backlinks/live
// the full list of possible parameters is available in documentation
var taskPostResponse = await httpClient.PostAsync("/v3/backlinks/backlinks/live", new StringContent(JsonConvert.SerializeObject(postData)));
var result = JsonConvert.DeserializeObject<dynamic>(await taskPostResponse.Content.ReadAsStringAsync());
// you can find the full list of the response codes here https://docs.dataforseo.com/v3/appendix/errors
if (result.status_code == 20000)
{
// do something with result
Console.WriteLine(result);
}
else
Console.WriteLine($"error. Code: {result.status_code} Message: {result.status_message}");
}
}
}
The above command returns JSON structured like this:
All POST data should be sent in the JSON format (UTF-8 encoding). The task setting is done using the POST method. When setting a task, you should send all task parameters in the task array of the generic POST array. You can send up to 2000 API calls per minute. The maximum number of requests that can be sent simultaneously is limited to 30.
You can specify the number of results you want to retrieve, filter and sort them.
Below you will find a detailed description of the fields you can use for setting a task.
Description of the fields for setting a task:
Field name
Type
Description
target
string
domain, subdomain or webpage to get backlinks for required field
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)
mode
string
results grouping type
optional field
possible grouping types: as_is – returns all backlinks one_per_domain – returns one backlink per domain one_per_anchor – returns one backlink per anchor
default value: as_is
custom_mode
object
detailed results grouping type
optional field
use this object to get a specific number of backlinks per field
if you use custom_mode, then mode will be ignored
example: "custom_mode": {"field": "domain", "value": 100}
field
string
response field
required field if you choose to specify custom_mode
possible values: anchor domain_from domain_from_country tld_from page_from_encoding page_from_language item_type page_from_status_code semantic_location
value
integer
number of backlinks to return per field
required field if you choose to specify custom_mode
can be set from 1 to 1000
filters
array
array of results filtering parameters
optional field you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported: regex, =, <>, in, not_in, like, not_like, ilike, not_ilike, regex, not_regex
you can use the % operator with like and not_like to match any string of zero or more characters
example: ["rank",">","80"]
The full list of possible filters is available here.
order_by
array
results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order
you should use a comma to set up a sorting type
example: ["rank,desc"] note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example: ["domain_from_rank,desc","page_from_rank,asc"]
offset
integer
offset in the results array of the returned backlinks
optional field
default value: 0
if you specify the 10 value, the first ten backlinks in the results array will be omitted and the data will be provided for the successive backlinks; Note: the maximum value is 20,000, use the search_after_token if you would like to offset more results
search_after_token
string
token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 100,000 results in a single request;
by specifying the unique search_after_token value from the response array, you will get the subsequent results of the initial task; search_after_token values are unique for each subsequent task Note: if the search_after_token is specified in the request, all other parameters should be identical to the previous request
limit
integer
the maximum number of returned backlinks
optional field
default value: 100
maximum value: 1000
backlinks_status_type
string
set what backlinks to return and count
optional field
you can use this field to choose what backlinks will be returned and used for aggregated metrics for your target;
possible values: all – all backlinks will be returned and counted; live – backlinks found during the last check will be returned and counted; lost – lost backlinks will be returned and counted;
default value: live
include_subdomains
boolean
indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true
include_indirect_links
boolean
indicates if indirect links to the target will be included in the results
optional field
if set to true, the results will include data on indirect links pointing to a page that either redirects to the target, or points to a canonical page
if set to false, indirect links will be ignored
default value: true
exclude_internal_backlinks
boolean
indicates if internal backlinks from subdomains to the target will be excluded from the results
optional field
if set to true, the results will not include data on internal backlinks from subdomains of the same domain as target
if set to false, internal links will be included in the results
default value: true
tag
string
user-defined task identifier
optional field the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response
As a response of the API server, you will receive JSON-encoded data containing a tasks array with the information specific to the set tasks.
Description of the fields in the results array:
Field name
Type
Description
version
string
the current version of the API
status_code
integer
general status code
you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions
status_message
string
general informational message
you can find the full list of general informational messages here
time
string
execution time, seconds
cost
float
total tasks cost, USD
tasks_count
integer
the number of tasks in the tasks array
tasks_error
integer
the number of tasks in the tasks array returned with an error
tasks
array
array of tasks
id
string
task identifier unique task identifier in our system in the UUID format
status_code
integer
status code of the task
generated by DataForSEO; can be within the following range: 10000-60000
you can find the full list of the response codes here
status_message
string
informational message of the task
you can find the full list of general informational messages here
time
string
execution time, seconds
cost
float
cost of the task, USD
result_count
integer
number of elements in the result array
path
array
URL path
data
object
contains the same parameters that you specified in the POST request
result
array
array of results
target
string
target domain in a POST array
mode
string
mode specified in a POST array
custom_mode
object
custom mode specified in a POST array
total_count
integer
total amount of results relevant the request
items_count
integer
the number of results returned in the items array
items
array
contains relevant backlinks and referring domains data
type
string
type of element = ‘backlink’
domain_from
string
domain referring to the target domain or webpage
url_from
string
URL of the page where the backlink is found
url_from_https
boolean
indicates whether the referring URL is secured with HTTPS
if true, the referring URL is secured with HTTPS
domain_to
string
domain the backlink is pointing to
url_to
string
URL the backlink is pointing to
url_to_https
boolean
indicates if the URL the backlink is pointing to is secured with HTTPS
if true, the URL is secured with HTTPS
tld_from
string
top-level domain of the referring URL
is_new
boolean
indicates whether the backlink is new
if true, the backlink was found on the page last time our crawler visited it
is_lost
boolean
indicates whether the backlink was removed
if true, the backlink or the entire page was removed
backlink_spam_score
integer
spam score of the backlink
learn more about how the metric is calculated on this help center page
rank
integer
backlink rank
rank that the given backlink passes to the target rank is calculated based on the method for node ranking in a linked database – a principle used in the original Google PageRank algorithm
learn more about the metric and how it is calculated in this help center article
page_from_rank
integer
page rank of the referring page page_from_rank is calculated based on the method for node ranking in a linked database – a principle used in the original Google PageRank algorithm
learn more about the metric and how it is calculated in this help center article
domain_from_rank
integer
domain rank of the referring domain domain_from_rank is calculated based on the method for node ranking in a linked database – a principle used in the original Google PageRank algorithm
learn more about the metric and how it is calculated in this help center article
domain_from_platform_type
array
platform types of the referring domain
example: "cms",
"blogs"
domain_from_is_ip
boolean
indicates if the domain is IP
if true, the domain functions as an IP address and does not have a domain name
domain_from_ip
string
IP address of the referring domain
domain_from_country
string
ISO country code of the referring domain
page_from_external_links
integer
number of external links found on the referring page
page_from_internal_links
integer
number of internal links found on the referring page
page_from_size
integer
size of the referring page, in bytes
example: 63357
page_from_encoding
string
character encoding of the referring page
example: utf-8
page_from_language
string
language of the referring page
in ISO 639-1 format
example: en
page_from_title
string
title of the referring page
page_from_status_code
integer
HTTP status code returned by the referring page
example: 200
first_seen
string
date and time when our crawler found the backlink for the first time
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example: 2019-11-15 12:57:46 +00:00
prev_seen
string
previous to the most recent date when our crawler visited the backlink
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example: 2019-11-15 12:57:46 +00:00
last_seen
string
most recent date when our crawler visited the backlink
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example: 2019-11-15 12:57:46 +00:00
item_type
string
link type
possible values: anchor, image, meta, canonical, alternate, redirect
attributes
array
link attributes of the referring links
example: nofollow
dofollow
boolean
indicates whether the backlink is dofollow
if false, the backlink is nofollow
original
boolean
indicates whether the backlink was present on the referring page when our crawler first visited it
alt
string
alternative text of the image
this field will be null if backlink type is not image
image_url
string
URL of the image
the URL leading to the image on the original resource or DataForSEO storage (in case the original source is not available)
anchor
string
anchor text of the backlink
text_pre
string
snippet before the anchor text
text_post
string
snippet after the anchor text
semantic_location
string
indicates semantic element in HTML where the backlink is found
you can get the full list of semantic elements here
examples: article, section, summary
links_count
integer
number of identical backlinks found on the referring page
group_count
integer
indicates total number of backlinks from this domain
for example, if mode is set to one_per_domain, this field will indicate the total number of backlinks coming from this domain
is_broken
boolean
indicates whether the backlink is broken
if true, the backlink is pointing to a page responding with a 4xx or 5xx status code
url_to_status_code
integer
status code of the referenced page
if the value is null, our crawler hasn’t yet visited the webpage the link is pointing to
example: 200
url_to_spam_score
integer
spam score of the referenced page
if the value is null, our crawler hasn’t yet visited the webpage the link is pointing to;
learn more about how the metric is calculated on this help center page
url_to_redirect_target
string
target url of the redirect
target page the redirect is pointing to
ranked_keywords_info
object
number of keywords for which the page is ranked in top search results
page_from_keywords_count_top_3
integer
number of keywords for which the page is ranked in top 3 search results
page_from_keywords_count_top_10
integer
number of keywords for which the page is ranked in top 10 search results
page_from_keywords_count_top_100
integer
number of keywords for which the page is ranked in top 100 search results
is_indirect_link
boolean
indicates whether the backlink is an indirect link
if true, the backlink is an indirect link pointing to a page that either redirects to url_to, or points to a canonical page
indirect_link_path
array
indirect link path
indicates a URL or a sequence of URLs that lead to url_to
type
string
indirect link type
possible values: redirect, canonical
status_code
integer
HTTP status code of the URL
url
string
indirect link URL
search_after_token
string
token for subsequent requests
by specifying the unique search_after_token when setting a new task, you will get the subsequent results of the initial task; search_after_token values are unique for each subsequent task