Ahrefs API v2 has been deprecated
This documentation is for the legacy version of our API (v2), which was discontinued on March 1st, 2024. Existing API v2 integration apps are not affected and continue to work as before, but new submissions are no longer accepted.
To switch to API v3, please contact our Enterprise team. Read about API v3.
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 |