Documentation - Ahrefs API

Documentation

Requesting Data

To retrieve data, an HTTP GET request must be sent to the API endpoint http://127.0.0.1:8001. 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 google.com in XML format using the authentication token 012345, perform the following request to get data from the Backlinks table: http://127.0.0.1:8001?from=backlinks&limit=100&target=google.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 support@ahrefs.com. 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.
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:
http://127.0.0.1:8001?token=012345&target=example.net&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:
http://127.0.0.1:8001?token=012345&target=example.net&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:
http://127.0.0.1:8001?token=012345&target=example.net&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:
http://127.0.0.1:8001?token=012345&target=example.net&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