Documentation

Requesting Data

To retrieve data, an HTTP GET request must be sent to the API endpoint https://apiv2.ahrefs.com. Options (what kind of data to retrieve, the target and the mode of the operation, filters, sorting, etc.) should be passed as the request parameters. For example, to retrieve a maximum of 100 backlinks that links to ahrefs.com in XML format using the authentication token 012345, perform the following request to get data from the Backlinks table: https://apiv2.ahrefs.com?from=backlinks&limit=100&target=ahrefs.com&mode=prefix&output=xml&token=012345

We recommend that you use our API Request Builder to help you create the request faster, saving you time and effort. If you need assistance in the creation of your API request, please keep in touch with our support at [email protected]. We are more than happy to help you.

Request Parameters

A request can have the parameters listed in the table below.

Parameter	Mandatory	Default	Explanation
token	+	n/a	Authentication token
select	−	*	List of columns to select
from	+	n/a	Table to select data from
target	+	n/a	Aim of a request: a domain, a directory or a URL
mode	+	n/a	Mode of operation: exact, domain, subdomains or prefix
where	−	−	"Where" condition to satisfy
having	−	−	"Having" condition to satisfy
order_by	−	−	List of columns to sort on
limit	−	1000	Number of results to return
output	−	json	Output format: xml, json or php

!Parameters must be encoded using UTF-8.

•  token

A token is used to authenticate and bill the user. Read more about the authentication process and how to obtain the token here.

•  from

Specify a table to select data from. See the list of the available tables below. Click the table name to know more about it in detail.

Table list

Table Name	Short Description
ahrefs_rank	Contains the URLs and the rankings.
anchors	Contains the anchor text and the # of backlinks, referring pages and referring domains that has it.
anchors_refdomains	Contains the # of anchors and backlinks with that anchor, per domain.
backlinks	Contains the backlinks and details of the referring pages, such as anchor and page title.
backlinks_new_lost	Contains the new or lost backlinks and details of the referring pages.
backlinks_new_lost_counters	Contains new and lost backlink totals.
backlinks_one_per_domain	Contains the backlinks and details of the referring pages, such as anchor and page title.
broken_backlinks	Contains the broken backlinks and details of the referring pages, such as anchor and page title.
broken_links	Contains the broken links and details of the referring pages, such as anchor and page title.
domain_rating	Contains the Domain Rating.
linked_anchors	Contains the anchor text and # of outgoing external and internal links that have it.
linked_domains	Contains the domains that the target links to.
linked_domains_by_type	Contains the domains that the target links to.
metrics	Contains metrics about the target, such as total # of backlinks, referring pages, etc.
metrics_extended	Contains additional metrics about the target, such as total # of referring domains, referring class C networks and referring IP addresses.
pages	Contains the crawled pages.
pages_extended	Contains additional info about the crawled pages, such as total # of backlinks, dofollow/nonfollow links, etc.
pages_info	Contains additional info about the crawled pages, such as IP address, canonical URL, social metrics etc.
positions_metrics	Contains the estimation of number of keywords, traffic and cost of the target URL.
refdomains	Contains the referring domains that contain backlinks to the target.
refdomains_by_type	Contains the referring domains that contain backlinks to the target.
refdomains_new_lost	Contains the new or lost referring domains and their details.
refdomains_new_lost_counters	Contains new and lost domains totals.
refips	Returns the referring IP addresses linking to the target.
subscription_info	Contains user subscription information.

Some of the requests return extra table(s) containing various statistics related to the data returned in the specified table.

•  select

Specify a comma-separated list of columns for the service to return. If the parameter is not set or is equal to “*”, all columns of the table are returned. Only the columns that are available in the “having” filter will be returned.

Example:
https://apiv2.ahrefs.com?token=012345&target=ahrefs.com&mode=exact&from=anchors&limit=1000&output=json&select=anchor,backlinks,refpages,refdomains,first_seen

! The list of columns only applies for the main table. It is not possible to specify a list of columns from other tables.

•  target and mode

Specify the aim of the request. The mode defines how the target will be interpreted. See example:

Target	mode = Exact	mode = Domain	mode = Subdomains	mode = Prefix
ahrefs.com/api/ apiv2.ahrefs.com	ahrefs.com/api/ apiv2.ahrefs.com/	ahrefs.com/* apiv2.ahrefs.com/*	*ahrefs.com/* *apiv2.ahrefs.com/*	ahrefs.com/api/* apiv2.ahrefs.com/*

! The links are stored URL-encoded in our database, so for "exact" and "prefix" modes to work, target URL components must be URL-encoded as well.
This means the target should be encoded twice: first to normalize special characters to the database format, second to pass it as a parameter in the request URL.

•  where and having

The table data can be filtered, returning only data that satisfies the specified comma-separated set of conditions.

{where|having}=<condition1>[,<condition2>[,...]]
A <condition> can be one of the following:

• <column><operator>"<value>"
• <function>(<column>,"<value>")

Operators are: =, <>, <, <=, >, >=.

Example:
https://apiv2.ahrefs.com?token=012345&target=ahrefs.com&mode=exact&from=anchors&limit=1000&output=xml&where=last_visited%3E%222013-11-01%22,first_seen%3E%222013-01-01%22&having=backlinks%3E10

! “=” should be URL-encoded as %3D.
“>” should be URL-encoded as %3E.
        “<” should be URL-encoded as %3C.
        “:” can be used in place of “=” for convenience.

string and date values must be enclosed in double quotes, for example: anchor="hello, world!"

! Open and closed quotations should be URL-encoded as %22.

Functions are:

• subdomain(<column>,"<domain>") - the condition is satisfied if a domain in the <column> is a subdomain of the provided <domain>;
• substring(<column>,"<value>") - the condition is satisfied if the provided <value> is a substring of the <column>;
• word(<column>,"<data>") - the condition is satisfied if the provided <value> appears as a separate word of the <column>.

! For some tables, the returned data is implicitly grouped before being returned. The “where” filter applies to the data before grouping, and the “having” filter applies to the grouped data. See column descriptions for the particular table to decide whether to use “where” or “having” for filtering.

Example:
https://apiv2.ahrefs.com?token=012345&target=ahrefs.com&mode=exact&from=backlinks_new_lost&limit=1000&output=xml&where=substring%28url_to,%22ample%22%29&having=word%28title,%22the%22%29&select=date,type,ahrefs_rank,domain_rating,url_from,url_to,encoding,http_code,title

! “(” should be URL-encoded as %28.
“)” should be URL-encoded as %29.

•   order_by

The returned table data can be sorted on the specified comma-separated list of columns. It is possible to sort either in ascending (default) or descending order using the keywords “asc” or “desc”, respectively.
order_by=<column1>[:<order1>][,<column2>[:<order2>][,...]]
It is only possible to sort on columns that can appear in the “having” filter.

Example:
https://apiv2.ahrefs.com?token=012345&target=ahrefs.com&mode=exact&from=ahrefs_rank&limit=1000&output=xml&order_by=ahrefs_rank%3Adesc

! “:” should be URL-encoded as %3A.

•  limit

The amount of retrieved data can be limited by using this parameter.

•  output

The table data can be returned in one of the following formats: xml, json, php.

---

Data Types

The supported data types are listed in the table below.

Type	Description
bool	Boolean value (true or false)
int	Signed integer value
float	Signed floating point value
string	Double-quoted string
date	Date and time in W3C format, double-quoted

---

Error Messages

Error text	Action
bad output: '<output>'	Check the 'output' parameter against the list of supported output formats
bad target: '<target>'	Check whether the 'target' parameter specifies a valid URL
bad mode: '<mode>'	Check the 'mode' parameter against the list of supported modes
<parameter>: mandatory parameter missing	Specify the mandatory parameter that is missing
<parameter>: value is not valid UTF-8	Check that the parameter '<parameter>' is UTF-8 encoded before URL-encoding
select: column '<column>' not found	Check the 'select' parameter against the list of columns for the table
from: table '<table>' not found	Check the 'from' paramater against the list of supported tables
order_by: bad sorting direction '<direction>'	Check the sorting direction specified in the 'order_by' parameter
order_by: bad syntax	Check syntax of the 'order_by' parameter
order_by: column '<column>' not found	Check the 'order_by' parameter against the list of columns for the table
where: bad syntax	Check syntax of the 'where' parameter
where: column '<column>' not found	Check the 'where' parameter against the list of columns for the table
where: function '<function>' cannot be applied to column '<column>'	Check the documentation for the function and the table
where: unknown function '<function>'	Check the 'where' parameter against the list of the supported functions
where: value '<value>' is not properly escaped	Check that '\' and '"' characters are escaped as '\\' and '\"', respectively
where: value '<value>' must be a <type>	Check the type of the value in the 'where' parameter against the column type in the documentation
having: bad syntax	Check syntax of the 'having' parameter
having: column '<column>' not found	Check the 'having' parameter against the list of columns for the table
having: function '<function>' cannot be applied to column '<column>'	Check the documentation for the function and the table
having: unknown function '<function>'	Check the 'having' parameter against the list of the supported functions
having: value '<value>' is not properly escaped	Check that '\' and '"' characters are escaped as '\\' and '\"', respectively
having: value '<value>' must be a <type>	Check the type of the value in the 'having' parameter against the column type in the documentation
no credit	Inform the user that he or she does not have rows left to spend
invalid token	Check that the provided authorization token is correct
internal error	Contact Ahrefs support
internal billing error	Contact Ahrefs support