SEMrush Projects API | SEMrush English

Projects API

Projects API allows users to create, edit and manage projects that use The Site Audit and Position Tracking tools. By using Projects API, you can track your web rivals’ and your own keyword rankings, discover local competitors, and fix websites’ on-page issues from one location, and much more.

Request Format

All API requests use such HTTP methods such as POST, PUT, GET or DELETE with JSON parameters and must contain your API Key.

Projects

List all existing projects

project_list

Price 100 API units per request

This request allows you to get a list of all projects, including their ID, project name and domain name, as well as tools that have been activated for each project.

Endpoint

https://api.semrush.com/

Requested URL (GET)

https://api.semrush.com/management/v1/projects?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Request parameters

Name	Value	Description
key*		An identification key assigned to a user after subscribing to SEMrush that is available via Profile page

Fields marked by an asterisk (*) are required

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example

{
"url": "mysite.com",
"tools": [],
"project_id": 643526670283248,
"project_name": "myproject"
}

Response parameters

Fields	Description
project_id	Project ID
project_name	The name of a project
url	The domain of a project
tools	List of project tools activated by a user

Get information about an existing project

project_get

Price 100 API units per request

This request allows you to get information regarding a project, including its ID, project name and domain name, as well as tools that have been activated for this project.

Requested URL (GET)

https://api.semrush.com/management/v1/projects/{id}?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Request parameters

Name	Value	Description
key*		An identification key assigned to a user after subscribing to SEMrush that is available via Profile page
id*		Project ID

Fields marked by an asterisk (*) are required

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example

{
"url": "mysite.com",
"tools": [],
"project_id": 643526670283248,
"project_name": "myproject"
}

Response parameters

Fields	Description
project_id	Project ID
project_name	The name of a project
url	The domain of a project
tools	List of project tools activated by a user

Create a new project

project_create

Price 100 API units per request

This request allows you to create a new project, which includes naming the project and choosing a domain.

Requested URL (POST)

https://api.semrush.com/management/v1/projects?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Request parameters

Name	Value	Description
key*		An identification key assigned to a user after subscribing to SEMrush that is available via Profile page
project_name*		Name of a user's project. Forbidden characters are ~`!#%'^&*=[]\/{}\|":<>?
url*		The domain of the project

Fields marked by an asterisk (*) are required

Request example

{"project_name":"myproject","url":"mysite.com"}

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example

{
"url": "mysite.com",
"tools": [],
"project_id": 643526670283248,
"project_name": "myproject"
}

Response parameters

Fields	Description
project_id	Project ID
project_name	The name of a project
url	The domain of a project
tools	List of project tools activated by a user

Update an existing project

project_update

Price 100 API units per request

This request allows you to update or change a project’s name.

Requested URL (PUT)

https://api.semrush.com/management/v1/projects?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Request parameters

Name	Value	Description
key*		An identification key assigned to a user after subscribing to SEMrush that is available via Profile page
project_id*		Project ID
project_name		Name of a user's project. Forbidden characters are ~`!#%'^&*=[]\/{}\|":<>?

Fields marked by an asterisk (*) are required

Request example

{"project_id":643526670283248, "project_name":"my old project"}

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example

{
"url": "mysite.com",
"tools": [],
"project_id": 643526670283248,
"project_name": "my old project"
}

Response parameters

Fields	Description
project_id	Project ID
project_name	The name of a project
url	The domain of a project
tools	List of project tools activated by a user

Delete an existing project

project_delete

Price 100 API units per request

This request allows you to delete a project, including its all of tool campaigns.

Requested URL (DELETE)

https://api.semrush.com/management/v1/projects/{id}?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Request parameters

Name	Value	Description
key*		An identification key assigned to a user after subscribing to SEMrush that is available via Profile page
id*		Project ID

Fields marked by an asterisk (*) are required

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Add keywords to an existing project

project_add_keywords

Price 100 API units per keyword added

This request allows you to add keywords to track to an existing project and group them with tags.

Requested URL (PUT)

https://api.semrush.com/management/v1/projects/{id}/keywords?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Request parameters

Name	Value	Description
key*		An identification key assigned to a user after subscribing to SEMrush that is available via Profile page
id*		Project ID
keywords		Keywords
tags		Tags for a keyword

Fields marked by an asterisk (*) are required

Request example

{"keywords":[{"keyword":"seo", "tags":["seo"]},{"keyword":"seotool", "tags":["seo"]}]}

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example

{
"url": "mysite.com",
"keywords": [
{
"keyword": "search tool",
"tags": ["search"],
"timestamp": 1391517755
},
{
"keyword": "search engine",
"tags": ["search"],
"timestamp": 1391517755
},
{
"keyword": "seo",
"tags": ["seo"],
"timestamp": 1491517755
},
{
"keyword": "seotool",
"tags": ["seo"],
"timestamp": 1491517755
}
],
"competitors": ["google.com","ebay.com","bing.com"],
"tools": [],
"project_id": 643526670283248,
"project_name": "my old project"
}

Response parameters

Fields	Description
project_id	Project ID
project_name	The name of a project
url	The domain of a project
tools	List of project tools activated by a user

Remove keywords from an existing project

project_delete_keywords

Price 100 API units per request

This request allows you to remove tracked keywords from an existing project.

Requested URL (DELETE)

https://api.semrush.com/management/v1/projects/{id}/keywords?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Request parameters

Name	Value	Description
key*		An identification key assigned to a user after subscribing to SEMrush that is available via Profile page
id*		Project ID
keywords		Keywords

Fields marked by an asterisk (*) are required

Request example

{"keywords":[{"keyword":"seo"},{"keyword":"seotool"}]}

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example

{
"url": "mysite.com",
"tools": [],
"project_id": 643526670283248,
"project_name": "my old project"
}

Response parameters

Fields	Description
project_id	Project ID
project_name	The name of a project
url	The domain of a project
tools	List of project tools activated by a user

Add competitors to an existing project

project_add_competitors

Price 100 API units per request

Requested URL (PUT)

https://api.semrush.com/management/v1/projects/{id}/competitors?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Request parameters

Name	Value	Description
key*		An identification key assigned to a user after subscribing to SEMrush that is available via Profile page
id*		Project ID
competitors		List of project competitors

Fields marked by an asterisk (*) are required

Request example

{"competitors":["yahoo.com"]}

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example

{
"url": "mysite.com",
"keywords": [
{
"keyword": "search tool",
"tags": ["search"],
"timestamp": 1391517755
},
{
"keyword": "search engine",
"tags": ["search"],
"timestamp": 1391517755
}
],
"competitors": ["google.com","ebay.com","bing.com","yahoo.com"],
"tools": [],
"project_id": 643526670283248,
"project_name": "myproject"
}

Response parameters

Fields	Description
project_id	Project ID
project_name	The name of a project
url	The domain of a project
tools	List of project tools activated by a user

Remove competitors from an existing project

project_delete_competitors

Price 100 API units per request

Requested URL (DELETE)

https://api.semrush.com/management/v1/projects/{id}/competitors?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Request parameters

Name	Value	Description
key*		An identification key assigned to a user after subscribing to SEMrush that is available via Profile page
id*		Project ID
competitors		List of project competitors

Fields marked by an asterisk (*) are required

Request example

{"competitors":["bing.com","yahoo.com"]}

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example

{
"url": "mysite.com",
"tools": [],
"project_id": 643526670283248,
"project_name": "myproject"
}

Response parameters

Fields	Description
project_id	Project ID
project_name	The name of a project
url	The domain of a project
tools	List of project tools activated by a user

Group keywords with tags in an existing project

project_add_tags

Price 100 API units per request

This request allows you to apply up to 5 tags to your tracked keywords.

Requested URL (PUT)

https://api.semrush.com/management/v1/projects/{id}/tags?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Request parameters

Name	Value	Description
key*		An identification key assigned to a user after subscribing to SEMrush that is available via Profile page
id*		Project ID
keywords		Keywords
tags		Tags for a keyword

Fields marked by an asterisk (*) are required

Request example

[{"tag":"seo", "keywords":["search tool", "search engine"]}]

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example

{
"url": "mysite.com",
"keywords": [
{
"keyword": "search tool",
"tags": ["search","seo"],
"timestamp": 1391517755
},
{
"keyword": "search engine",
"tags": ["search","seo"],
"timestamp": 1391517755
}
],
"competitors": ["google.com","ebay.com"],
"tools": [],
"project_id": 643526670283248,
"project_name": "myproject"
}

Response parameters

Fields	Description
project_id	Project ID
project_name	The name of a project
url	The domain of a project
tools	List of project tools activated by a user

Remove tags from keywords in an existing project

project_remove_tags

Price 100 API units per request

This request allows you to remove tags from tracked keywords.

Requested URL (DELETE)

https://api.semrush.com/management/v1/projects/{id}/tags?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Request parameters

Name	Value	Description
key*		An identification key assigned to a user after subscribing to SEMrush that is available via Profile page
id*		Project ID
keywords		Keywords
tag		Tags for a keyword

Fields marked by an asterisk (*) are required

Request example

[{"tag":"seo", "keywords":["search tool", "search engine"]}]

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example

{
"url": "mysite.com",
"tools": [],
"project_id": 643526670283248,
"project_name": "myproject"
}

Response parameters

Fields	Description
project_id	Project ID
project_name	The name of a project
url	The domain of a project
tools	List of project tools activated by a user

Position Tracking Tool

Management

The base URL for all requests is:

https://api.semrush.com/management/v1/projects/{ID}/tracking/{METHOD}

Where {ID} - id of the project and {METHOD} - name of one of the available methods.

Enable the Position Tracking Tool in a project

tracking_enable

Price 100 API units per request

This request allows you to enable the Position Tracking tool in a project that unlock possibility to get daily updates on a project domain and its competitors’ keyword rankings.

Request parameters

Name	Value	Description
key*	XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX	An identification key assigned to a user after subscribing to SEMrush that is available via Profile page
tracking_url_type*	one of: rootdomain, subdomain, subfolder, url	tracked URL's type
tracking_url*	string	tracked URL
country_id*	integer	country id
region_id	integer	region id
city_id	integer	city id
weekly_notification*	1 or 0	The value "1" in this parameter means that weekly email-sending is enabled The value "0" in this parameter means that weekly email-sending is disabled
first_letter	1 (default) or 0	1 - send the letter to login email when first data is available 0 - do not send the letter to login email when first data is available
timezone	integer	Time zone (crawling starts at 5am in a specified time zone)
device	one of: desktop, phone, tablet	Target device

Fields marked by an asterisk (*) are required

Request example

POST /enable?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

{"tracking_url": "ebay.com", "tracking_url_type": "rootdomain", "country_id": "2840", "weekly_notification": "1", "device": "desktop"}

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Enable/Disable email-sending containing project statistics

tracking_notification_update

Price 100 API units per request

This request allows you to enable or disable weekly emails with project statistics.

Request parameters

Name	Value	Description
key*	XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX	An identification key assigned to a user after subscribing to SEMrush that is available via Profile page

Fields marked by an asterisk (*) are required

Request example

PUT /notifications?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
DELETE /notifications?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Available regions

One of the required parameters for tracking campaign creation is country_id. You can get a list of available countries and their corresponding regions and cities by sending these requests.

The base URL for all requests is:

https://api.semrush.com/management/v1/info/{METHOD}

Where {METHOD} - name of one of the available methods.

Get a list of countries

get_countries

Price 100 API units per request

This request allows you to get a list of countries for which geolocation for a project can be chosen.

Request parameters

Name	Value	Description
key*	XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX	An identification key assigned to a user after subscribing to SEMrush that is available via Profile page

Fields marked by an asterisk (*) are required

Request example

GET /countries?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example

{
"0": {
"id": 2840,
"name": "United States"
},
"1": {
"id": 2124,
"name": "Canada"
},
"2": {
"id": 2826,
"name": "United Kingdom"
},
...
}

Return values

Name	Value	Description
id	integer	country id
name	string	country name

Get a list of regions

get_regions

Price 100 API units per request

This request allows you to get a list of regions for which geolocation for a project can be chosen.

Request parameters

Name	Value	Description
key*	XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX	An identification key assigned to a user after subscribing to SEMrush that is available via Profile page
country_id*	integer	country id

Fields marked by an asterisk (*) are required

Request example

GET /countries/{country_id}/regions?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example

{
"0": {
"id": 21133,
"name": "Alabama"
},
"1": {
"id": 21132,
"name": "Alaska"
},
"2": {
"id": 21136,
"name": "Arizona"
},
...
}

Return values

Name	Value	Description
id	integer	region id
name	string	region name

Get a list of cities

get_cities

Price 100 API units per request

This request allows you to get a list of cities for which geolocation for a project can be chosen.

Request parameters

Name	Value	Description
key*	XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX	An identification key assigned to a user after subscribing to SEMrush that is available via Profile page
country_id*	integer	country id
region_id*	integer	region id

Fields marked by an asterisk (*) are required

Request example

GET /countries/{country_id}/regions/{region_id}/cities?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example

{
"0": {
"id": 1013370,
"name": "Ajo"
},
"1": {
"id": 1013371,
"name": "Alpine"
},
"2": {
"id": 1013372,
"name": "Amado"
},
...
}

Return values

Name	Value	Description
id	integer	city id
name	string	city name

Reports

All report-related requests require the use of the HTTP GET request method. The base URL for all requests is:

https://api.semrush.com/reports/v1/projects/{ID}/tracking/

Where {ID} - id of the project.

Attention! For requests that use the url parameter, you must use a proper mask.

Url type	Mask example
rootdomain	.ebay.com/
subdomain	www.ebay.com/*
subfolder	ebay.com/motors/*
url	http://www.ebay.com/motors/

URLs with a trailing slash (/) and those without this sign are different ones. The positions of these URLs may also differ in search engine results.

Campaign Dates

tracking_campaign_dates

Price 100 API units per request

This request returns a list of dates for which a campaign was collected.

Request parameters

Name	Value	Description
key*	XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX	An identification key assigned to a user after subscribing to SEMrush that is available via Profile page
action*	report
type*	tracking_campaign_dates	request type

Fields marked by an asterisk (*) are required

Request example

GET /?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&action=report&type=tracking_campaign_dates

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example

{
"total": "9",
"last_crawl": "2",
"data": {
"0": {
"Dt": "20140401",
},
"1": {
"Dt": "20140402",
},
"2": {
"Dt": "20140403",
},
"3": {
"Dt": "20140404",
},
...
}
}

Return values

Name	Value	Description
total	integer	number of results
last_crawl	integer	time since the last crawl
Dt	date in YYYYMMDD format	date

Organic Overview

tracking_overview_organic

Price 100 API units per request

This request allows you to get an overview of a domain’s rankings in the Google top 100, and to see new and lost keywords, search terms with improved or decreased rankings, and changes in its ranking over a selected period.

Request parameters

Name	Value	Description
key*	XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX	An identification key assigned to a user after subscribing to SEMrush that is available via Profile page
action*	report
type*	tracking_overview_organic	request type
url*	string	tracked URL or competitor URL (with mask)
display_tags	string	tags separated by the '\|' symbol
date_begin	date in YYYYMMDD format	starting date of a selected period
date_end	date in YYYYMMDD format	end date of a selected period
linktype_filter	0 - Include local pack rankings in all reports. This is the default value. 1 - Show only local pack rankings in all reports 2 - Exclude local pack rankings from all reports	local pack filter
serp_feature_filter	fsn: Featured snippet geo: Local pack rev: Reviews stl: Site links vid: Video vib: Featured video new: Top stories rel: People also ask img: Images twt: Twitter knw: Instant answer kng: Knowledge panel shp: Shopping ads adt: AdWords top adb: AdWords bottom	Use this filter to see keywords that have certain SERP features on a SERP.

Fields marked by an asterisk (*) are required

Request example

GET /?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&action=report&type=tracking_overview_organic&date_begin=20140405&date_end=20140411&linktype_filter=0&url=*.ebay.com%2F*&serp_feature_filter=fsn

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example


{
"total": 199,
"visibility": 15.9602,
"differenceVisibility": 1.7159,
"all": 146,
"all_improved": 67,
"all_declined": 32,
"all_difference": 3,
"all_left": 3,
"all_entered": 6,
"top3": 36,
"top3_improved": 8,
"top3_declined": 2,
"top3_difference": 2,
"top3_left": 1,
"top3_entered": 3,
"top10": 67,
"top10_improved": 19,
"top10_declined": 13,
"top10_difference": 6,
"top10_left": 1,
"top10_entered": 7,
"top20": 97,
"top20_improved": 36,
"top20_declined": 19,
"top20_difference": 10,
"top20_left": 1,
"top20_entered": 11,
"data": {}
}

Return values

Name	Value	Description
total	integer	number of results
visibility	percentage	visibility index
differenceVisibility	percentage	visibility index
all	integer	The number of keywords that bring a domain to the top 100 search results
all_difference	integer	changes in keywords that bring a domain to the top 100 search results
all_improved	integer	The number of improved keywords that bring a domain to the top 100 search results
all_declined	integer	The number of declined keywords that bring a domain to the top 100 search results
all_left	integer	The number of keywords that no longer bring a domain to the top 100 search results
all_entered	integer	The number of new keywords bringing a domain to the top 100 search results
top3	integer	number of keywords that bring a domain to the top 3 search results
top3_improved	integer	The number of improved keywords that bring a domain to the top 3 search results
top3_declined	integer	The number of declined keywords that bring a domain to the top 3 search results
top3_difference	integer	changes in keywords that bring a domain to the top 3 search results
top3_left	integer	The number of keywords that no longer bring a domain to the top 3 search results
top3_entered	integer	The number of new keywords bringing a domain to the top 3 search results
top10	integer	number of keywords that bring a domain to the first page of search results
top10_improved	integer	The number of improved keywords that bring a domain to the first page of search results
top10_declined	integer	The number of declined keywords that bring a domain to the first page of search results
top10_difference	integer	changes in keywords that bring a domain to the first page of search results
top10_left	integer	The number of keywords that no longer bring a domain to the first page of search results
top10_entered	integer	The number of new keywords bringing a domain to the first page of search results
top20	integer	number of keywords that bring a domain to the first two pages of search results
top20_improved	integer	The number of improved keywords that bring a domain to the first two pages of search results
top20_declined	integer	The number of declined keywords that bring a domain to the first two pages of search results
top20_difference	integer	changes in keywords that bring a domain to the first two pages of search results
top20_left	integer	The number of keywords that no longer bring a domain to the first two pages of search results
top20_entered	integer	The number of new keywords bringing a domain to the first two pages of search results
data	array	array of positions and numbers of keywords on this position (from 0 to 99)

Organic Positions report

tracking_position_organic

Price 100 API units per line

This report lists all keywords from a tracking campaign, the positions of up to 6 domains for these keywords in Google’s top 100 organic search results for these keywords, and position changes over a selected time period.

Request parameters

Name	Value	Description
key*	XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX	An identification key assigned to a user after subscribing to SEMrush that is available via Profile page
action*	report
type*	tracking_position_organic	request type
top_filter	top_3, top_3_income, top_3_leave, top_3_down, top_3_up, top_1page, top_1page_income, top_1page_leave, top_1page_down, top_1page_up, top_2page, top_2page_income, top_2page_leave, top_2page_down, top_2page_up, top_100, top_100_income, top_100_leave, top_100_down, top_100_up	positions filter
url*	string	tracked URL or competitor URL (with mask)
date_begin	date in YYYYMMDD format	starting date of a selected period
date_end	date in YYYYMMDD format	end date of a selected period
display_tags	string	tags separated by the '\|' symbol
display_filter	string	filter for columns Ph, Nq, Cp
display_limit	integer	number of returned results
display_offset	integer	This parameter allows you to skip a specified number of lines before sending results
display_sort	ph_asc, ph_desc, {DOMAIN_N}_pos_asc, {DOMAIN_N}_pos_desc, {DOMAIN_N}_be_asc, {DOMAIN_N}_be_desc, {DOMAIN_N}_di_asc, {DOMAIN_N}_di_desc, cp_asc, cp_desc, nq_desc, nq_asc	report sortings
linktype_filter	0 - Include local pack rankings in all reports. This is the default value. 1 - Show only local pack rankings in all reports 2 - Exclude local pack rankings from all reports	local pack filter
serp_feature_filter	fsn: Featured snippet geo: Local pack rev: Reviews stl: Site links vid: Video vib: Featured video new: Top stories rel: People also ask img: Images twt: Twitter knw: Instant answer kng: Knowledge panel shp: Shopping ads adt: AdWords top adb: AdWords bottom	Use this filter to see keywords that have certain SERP features on a SERP.

Fields marked by an asterisk (*) are required

Request example

GET /?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&action=report&type=tracking_position_organic&display_limit=10&display_offset=0&display_sort=20140411_asc&date_begin=20140405&date_end=20140411&display_filter=&url=*.ebay.com%2F*&linktype_filter=0&serp_filter_filter=fsn

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example


{
"total": "199",
"limit": "10",
"offset": "0",
"data": {
"0": {
"Pi": "1209571576516105373",
"Ph": "pig trough",
"Tg": {},
"Cp": "0.25",
"Nq": "1300",
"Dt": {
"20150414": {
"*.alibaba.com/*": "1",
"*.aliexpress.com/*": ""
},
"20150415": {
"*.alibaba.com/*": "1",
"*.aliexpress.com/*": ""
},
"20150416": {
"*.alibaba.com/*": "",
"*.aliexpress.com/*": ""
},
"20150417": {
"*.alibaba.com/*": "1",
"*.aliexpress.com/*": ""
},
"20150418": {
"*.alibaba.com/*": "1",
"*.aliexpress.com/*": ""
},
"20150419": {
"*.alibaba.com/*": "1",
"*.aliexpress.com/*": ""
},
"20150420": {
"*.alibaba.com/*": "1",
"*.aliexpress.com/*": ""
}
},
"Lt": {
"20150414": {
"*.alibaba.com/*": "org",
"*.aliexpress.com/*": "org"
},
"20150415": {
"*.alibaba.com/*": "org",
"*.aliexpress.com/*": "org"
},
...
},
"Lu": {
"20150414": {
"*.alibaba.com/*": "http://www.alibaba.com/",
"*.aliexpress.com/*": "http://www.aliexpress.com/"
},
"20150415": {
"*.alibaba.com/*": "http://www.alibaba.com/",
"*.aliexpress.com/*": "http://www.aliexpress.com/"
},
...
},
"Be": {
"*.alibaba.com/*": "1",
"*.aliexpress.com/*": ""
},
"Fi": {
"*.alibaba.com/*": "1",
"*.aliexpress.com/*": ""
},
"Diff": {
"*.alibaba.com/*": 0,
"*.aliexpress.com/*": 0
},
"Diff1": {
"*.alibaba.com/*": 0,
"*.aliexpress.com/*": 0
},
"Diff7": {
"*.alibaba.com/*": 0,
"*.aliexpress.com/*": 0
},
"Diff30": {
"*.alibaba.com/*": 0,
"*.aliexpress.com/*": 0
}
},
...
}

Return values

Name	Value	Description
total	integer	number of results
limit	integer	number of returned results
offset	integer	This parameter allows you to skip a specified number of lines before sending results
Pi	string	keyword ID
Ph	string	keyword
Tg	array	tags for a keyword
Cp	integer	Average price in U.S. dollars advertisers pay for a user’s click on an ad containing the given keyword (Google AdWords).
Nq	integer	The average number of times users have searched for a given keyword per month. We calculate this value over the last 12 months.
Dt	array	array of dates and positions (dates in format "YYYYMMDD")
Lt	string	Ranking type "org" - organic ranking "geo" - local pack ranking
Lu	array	Landing URLs
Be	array	Position at the beginning of specified period
Fi	array	Position at the end of specified period
Sf	array	Serp features on a SERP in the specified date
Vi	array	Visibility of domain on a SERP in the specified date
Tr	array	Estimated traffic in the specified date
Diff	array	Position difference for specified period
Diff1	array	Position difference for 1-day period
Diff7	array	Position difference for 1-week period
Diff30	array	Position difference for 1-month period

AdWords Positions report

tracking_position_adwords

Price 100 API units per line

This report lists all keywords from a tracking campaign, the positions of up to 6 domains for these keywords in Google’s paid search results, and position changes over a selected time period.

Request parameters

Name	Value	Description
key*	XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX	An identification key assigned to a user after subscribing to SEMrush that is available via Profile page
action*	report
type*	tracking_position_adwords	request type
url*	string	tracked URL or competitor URL (with mask)
date_begin	date in YYYYMMDD format	starting date of a selected period
date_end	date in YYYYMMDD format	end date of a selected period
display_tags	string	tags separated by the '\|' symbol
display_filter	string	filter for columns Ph, Nq, Cp
display_limit	integer	number of returned results
display_offset	integer	This parameter allows you to skip a specified number of lines before sending results
display_sort	ph_asc, ph_desc, {DOMAIN_N}_pos_asc, {DOMAIN_N}_pos_desc, {DOMAIN_N}_be_asc, {DOMAIN_N}_be_desc, {DOMAIN_N}_di_asc, {DOMAIN_N}_di_desc, cp_asc, cp_desc, nq_desc, nq_asc	report sortings

Fields marked by an asterisk (*) are required

Request example

GET /?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&action=report&type=tracking_position_adwords&display_limit=10&display_offset=0&display_sort=20140411_asc&date_begin=20140405&date_end=20140411&display_filter=&url=*.ebay.com%2F*

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example


{
"total": "199",
"limit": "10",
"offset": "0",
"data": {
"0": {
"Pi": "1329428353566010647",
"Ph": "alibaba express",
"Tg": {},
"Cp": "0.65",
"Nq": "18100",
"Dt": {
"20150414": {
"*.alibaba.com/*": "1",
"*.aliexpress.com/*": "2"
},
"20150415": {
"*.alibaba.com/*": "1",
"*.aliexpress.com/*": "2"
},
"20150416": {
"*.alibaba.com/*": "",
"*.aliexpress.com/*": ""
},
"20150417": {
"*.alibaba.com/*": "1",
"*.aliexpress.com/*": "2"
},
"20150418": {
"*.alibaba.com/*": "1",
"*.aliexpress.com/*": ""
},
"20150419": {
"*.alibaba.com/*": "1",
"*.aliexpress.com/*": "2"
},
"20150420": {
"*.alibaba.com/*": "1",
"*.aliexpress.com/*": "2"
}
},
"Lu": {
"20150414": {
"*.alibaba.com/*": "http://www.alibaba.com/",
"*.aliexpress.com/*": "http://www.aliexpress.com/"
},
"20150415": {
"*.alibaba.com/*": "http://www.alibaba.com/",
"*.aliexpress.com/*": "http://www.aliexpress.com/"
},
...
},
"Be": {
"*.alibaba.com/*": "1",
"*.aliexpress.com/*": "2"
},
"Fi": {
"*.alibaba.com/*": "1",
"*.aliexpress.com/*": "2"
},
"Diff": {
"*.alibaba.com/*": 0,
"*.aliexpress.com/*": 0
},
"Diff1": {
"*.alibaba.com/*": 0,
"*.aliexpress.com/*": 0
},
"Diff7": {
"*.alibaba.com/*": 0,
"*.aliexpress.com/*": 0
},
"Diff30": {
"*.alibaba.com/*": 0,
"*.aliexpress.com/*": 0
}
},
...
}

Return values

Name	Value	Description
total	integer	number of results
limit	integer	number of returned results
offset	integer	This parameter allows you to skip a specified number of lines before sending results
Pi	string	keyword ID
Ph	string	keyword
Tg	array	tags for a keyword
Cp	integer	Average price in U.S. dollars advertisers pay for a user’s click on an ad containing the given keyword (Google AdWords).
Nq	integer	The average number of times users have searched for a given keyword per month. We calculate this value over the last 12 months.
Dt	array	array of dates and positions (dates in format "YYYYMMDD")
Lu	array	Landing URLs
Be	array	Position at the beginning of specified period
Fi	array	Position at the end of specified period
Diff	array	Position difference for specified period
Diff1	array	Position difference for 1-day period
Diff7	array	Position difference for 1-week period
Diff30	array	Position difference for 1-month period

Organic Competitors Discovery report

tracking_competitors_organic

Price 1000 API units per line

This reports allows to see the list of domains that appear in Google’s top 100 organic search results for the keywords from a tracking campaign within a chosen location; competitors’ average position in search results, their visibility, as well as these results over a selected period, are taken into account to build this list.

Request parameters

Name	Value	Description
key*	XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX	An identification key assigned to a user after subscribing to SEMrush that is available via Profile page
action*	report
type*	tracking_competitors_organic	request type
url	string	tracked URL
url_type*	one of: rootdomain, subdomain, subfolder, url	type of a competitor URL
black_list	string	exclude domains from results (separated by the '\|' symbol)
top_start	integer	start depth range
top_end	integer	end depth range
date_begin	date in YYYYMMDD format	starting date of a selected period
date_end	date in YYYYMMDD format	end date of a selected period
display_tags	string	tags separated by the '\|' symbol
display_limit	integer	number of returned results
display_offset	integer	This parameter allows you to skip a specified number of lines before sending results
display_sort	ur_asc, ur_desc, {DATE}_asc, {DATE}_desc, cl_asc, cl_desc, cd_asc, cd_desc, av_asc, av_desc	report sortings
linktype_filter	0 - Include local pack rankings in all reports. This is the default value. 1 - Show only local pack rankings in all reports 2 - Exclude local pack rankings from all reports	local pack filter
serp_feature_filter	fsn: Featured snippet geo: Local pack rev: Reviews stl: Site links vid: Video vib: Featured video new: Top stories rel: People also ask img: Images twt: Twitter knw: Instant answer kng: Knowledge panel shp: Shopping ads adt: AdWords top adb: AdWords bottom	Use this filter to see keywords that have certain SERP features on a SERP.

Fields marked by an asterisk (*) are required

Request example

GET /?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&action=report&type=tracking_competitors_organic&display_limit=10&display_offset=0&display_sort=20140411_desc&date_begin=20140405&date_end=20140411&top_start=1&top_end=10&url_type=rootdomain&linktype_filter=0&serp_feature_filter=fsn

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example


{
"Md": {
"Ur": "alibaba.com",
"Dt": {
"20150414": {
"Mc": "143",
"Av": "20",
"Sq": "20",
"Cl": "14.24"
},
"20150420": {
"Mc": "146",
"Av": "19",
"Sq": "19",
"Cl": "15.96"
}
},
"Cd": "1.72"
},
"total": "12706",
"limit": "10",
"offset": "0",
"data": {
"0": {
"Ur": "alibaba.com",
"Dt": {
"20150414": {
"Mc": "143",
"Av": "20",
"Sq": "20",
"Cl": "14.24"
},
"20150420": {
"Mc": "146",
"Av": "19",
"Sq": "19",
"Cl": "15.96"
}
},
"Cd": "1.72"
},
...
}
}

Return values

Name	Value	Description
total	integer	number of results
limit	integer	number of returned results
offset	integer	This parameter allows you to skip a specified number of lines before sending results
Ur	string	competitor URL
Dt	array	dates and positions (date in YYYYMMDD format)
Cl	float	visibility
Cd	float	visibility change for specified period
Av	integer	average position
Sq	integer	position deviation
Mc	integer	number of keywords

AdWords Competitors Discovery report

tracking_competitors_adwords

Price 1000 API units per line

This report allows you to see domains that appear in Google’s paid search results for the keywords from a tracking campaign within a chosen location.

Request parameters

Name	Value	Description
key*	XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX	An identification key assigned to a user after subscribing to SEMrush that is available via Profile page
action*	report
type*	tracking_competitors_adwords	request type
url	string	tracked URL
url_type*	one of: rootdomain, subdomain, subfolder, url	type of a competitor URL
black_list	string	exclude domains from results (separated by the '\|' symbol)
top_start	integer	start depth range
top_end	integer	end depth range
date_begin	date in YYYYMMDD format	starting date of a selected period
date_end	date in YYYYMMDD format	end date of a selected period
display_tags	string	tags separated by the '\|' symbol
display_limit	integer	number of returned results
display_offset	integer	This parameter allows you to skip a specified number of lines before sending results
display_sort	ur_asc, ur_desc, {DATE}_asc, {DATE}_desc, cl_asc, cl_desc, cd_asc, cd_desc, av_asc, av_desc	report sortings

Fields marked by an asterisk (*) are required

Request example

GET /?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&action=report&type=tracking_competitors_adwords&display_limit=10&display_offset=0&display_sort=20140411_desc&date_begin=20140405&date_end=20140411&top_start=1&top_end=10&url_type=rootdomain

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example


{
"Md": {
"Ur": "alibaba.com",
"Dt": {
"20150414": {
"Mc": "22",
"Av": "7",
"Sq": "17",
"Cl": "9.25"
},
"20150420": {
"Mc": "18",
"Av": "1",
"Sq": "2",
"Cl": "8.74"
}
},
"Cd": "-0.50",
"Ps": 426
},
"total": "504",
"limit": "10",
"offset": "0",
"data": {
"0": {
"Ur": "isexdoll.com",
"Dt": {
"20150414": {
"Mc": "0",
"Av": "0",
"Sq": "0",
"Cl": "0.00"
},
"20150420": {
"Mc": "7",
"Av": "3",
"Sq": "3",
"Cl": "2.81"
}
},
"Cd": "2.81"
},
...
}
}

Return values

Name	Value	Description
total	integer	number of results
limit	integer	number of returned results
offset	integer	This parameter allows you to skip a specified number of lines before sending results
Ur	string	competitor URL
Dt	array	dates and positions (date in YYYYMMDD format)
Cl	float	visibility
Cd	float	visibility change for specified period
Av	integer	average position
Sq	integer	position deviation
Mc	integer	number of keywords

Organic Visibility Index report

tracking_visibility_organic

Price 100 API units per request

This report provides a domain’s visibility that shows a website’s progress in Google’s top 100 organic search results for keywords from a tracking campaign, as well as visibility changes over a selected period.

Request parameters

Name	Value	Description
key*	XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX	An identification key assigned to a user after subscribing to SEMrush that is available via Profile page
action*	report
type*	tracking_visibility_organic	request type
url*	string	tracked URL or competitor URL (with mask)
date_begin	date in YYYYMMDD format	starting date of a selected period
date_end	date in YYYYMMDD format	end date of a selected period
display_tags	string	tags separated by the '\|' symbol
linktype_filter	0 - Include local pack rankings in all reports. This is the default value. 1 - Show only local pack rankings in all reports 2 - Exclude local pack rankings from all reports	local pack filter

Fields marked by an asterisk (*) are required

Request example

GET /?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&action=report&type=tracking_visibility_organic&date_begin=20140401&date_end=20140411&url=*.ebay.com%2F*&linktype_filter=0

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example

{
"total": "9",
"data": {
"0": {
"Dt": "20140401",
"Vi": 7,
"Vr": 96
},
"1": {
"Dt": "20140402",
"Vi": 7,
"Vr": 96
},
"2": {
"Dt": "20140403",
"Vi": 7,
"Vr": 96
},
"3": {
"Dt": "20140404",
"Vi": 7,
"Vr": 96
},
...
}
}

Return values

Name	Value	Description
total	integer	number of results
Dt	date in YYYYMMDD format	date
Vi	integer	absolute visibility value
Vr	float	relative visibility value

AdWords Visibility Index report

tracking_visibility_adwords

Price 100 API units per request

This report provides a domain’s visibility that shows a website’s progress in Google’s paid search results for keywords from a tracking campaign, as well as visibility changes over a selected period.

Request parameters

Name	Value	Description
key*	XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX	An identification key assigned to a user after subscribing to SEMrush that is available via Profile page
action*	report
type*	tracking_visibility_adwords	request type
url*	string	tracked URL or competitor URL (with mask)
date_begin	date in YYYYMMDD format	starting date of a selected period
date_end	date in YYYYMMDD format	end date of a selected period
display_tags	string	tags separated by the '\|' symbol

Fields marked by an asterisk (*) are required

Request example

GET /?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&action=report&type=tracking_visibility_adwords&date_begin=20140401&date_end=20140411&url=*.ebay.com%2F*

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example

{
"total": "9",
"data": {
"0": {
"Dt": "20140401",
"Vi": 7,
"Vr": 96
},
"1": {
"Dt": "20140402",
"Vi": 7,
"Vr": 96
},
"2": {
"Dt": "20140403",
"Vi": 7,
"Vr": 96
},
"3": {
"Dt": "20140404",
"Vi": 7,
"Vr": 96
},
...
}
}

Return values

Name	Value	Description
total	integer	number of results
Dt	date in YYYYMMDD format	date
Vi	integer	absolute visibility value
Vr	integer	relative visibility value

Organic Landing Pages report

tracking_landing_pages_organic

Price 1000 API units per line

This report lists all landing pages of selected domain for current tracking campaign. For each landing page all the keywords that this landing page ranks for are reported.

Request parameters

Name	Value	Description
key*	XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX	An identification key assigned to a user after subscribing to SEMrush that is available via Profile page
action*	report
type*	tracking_landing_pages_organic	request type
url*	string	tracked URL or competitor URL (with mask)
date_begin	date in YYYYMMDD format	starting date of a selected period
date_end	date in YYYYMMDD format	end date of a selected period
display_tags	string	tags separated by the '\|' symbol
display_filter	string	filter for columns Ph, Nq, Cp
display_limit	integer	number of returned results
display_offset	integer	This parameter allows you to skip a specified number of lines before sending results
display_sort	ph_asc, ph_desc, {DOMAIN_N}_pos_asc, {DOMAIN_N}_pos_desc, {DOMAIN_N}_be_asc, {DOMAIN_N}_be_desc, {DOMAIN_N}_di_asc, {DOMAIN_N}_di_desc, cp_asc, cp_desc, nq_desc, nq_asc	report sortings
newlost_filter	new, lost	return only new or lost urls
linktype_filter	0 - Include local pack rankings in all reports. This is the default value. 1 - Show only local pack rankings in all reports 2 - Exclude local pack rankings from all reports	local pack filter

Fields marked by an asterisk (*) are required

Request example

GET /?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&action=report&type=tracking_landing_pages_organic&display_sort=1_mc_desc&date_begin=20180207&date_end=20180207&display_limit=100&display_filter=&display_offset=0&display_tags=&url=semrush.com/blog&filter_url=&newlost_filter=&linktype_filter=0

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example


{
"total": 37,
"state": "0",
"limit": 100,
"offset": 0,
"new": 0,
"lost": 0,
"keywords": 107,
"Pc": {
"http": 0,
"https": 37
},
"data": {
"0": {
"Ur": "https://www.semrush.com/blog/topsy-is-dead-alternative-social-analytics-tools-you-need-to-use-now/",
"Tp": "",
"Dt": {
"20180207": {
"Mc": 9,
"Av": 2.22,
"Tr": 61.518333,
"Tc": 116.040433,
"Rq": 19620
},
"Diff": {
"Mc": 0,
"Av": 0,
"Tr": 0,
"Tc": 0,
"Rq": 0
}
},
"Kw": [
{
"Pi": "7922908393917093815",
"Ph": "topsy analytics",
"Tp": "",
"Rq": 320,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 1,
"Diff": 0
},
"Tr": {
"20180207": 3.882667,
"Diff": 0
},
"Tc": {
"20180207": 25.819733,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "1522738860508378941",
"Ph": "topsy com analytics",
"Tp": "",
"Rq": 170,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 1,
"Diff": 0
},
"Tr": {
"20180207": 2.062667,
"Diff": 0
},
"Tc": {
"20180207": 4.682253,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "3772292990852912364",
"Ph": "topsy social",
"Tp": "",
"Rq": 90,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 1,
"Diff": 0
},
"Tr": {
"20180207": 1.092,
"Diff": 0
},
"Tc": {
"20180207": 0,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "8747962949595138851",
"Ph": "topsy twitter analytics",
"Tp": "",
"Rq": 90,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 1,
"Diff": 0
},
"Tr": {
"20180207": 1.092,
"Diff": 0
},
"Tc": {
"20180207": 9.67512,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "9069259884330927019",
"Ph": "what is topsy com",
"Tp": "",
"Rq": 90,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 2,
"Diff": 0
},
"Tr": {
"20180207": 0.375,
"Diff": 0
},
"Tc": {
"20180207": 0,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "2019165307386841491",
"Ph": "topsy com",
"Tp": "",
"Rq": 5400,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 3,
"Diff": 0
},
"Tr": {
"20180207": 17.1,
"Diff": 0
},
"Tc": {
"20180207": 41.382,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "13769451381664187323",
"Ph": "topsy.com",
"Tp": "",
"Rq": 880,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 3,
"Diff": 0
},
"Tr": {
"20180207": 2.786667,
"Diff": 0
},
"Tc": {
"20180207": 2.870267,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "2409524746484837701",
"Ph": "topsy",
"Tp": "",
"Rq": 12100,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 4,
"Diff": 0
},
"Tr": {
"20180207": 31.863333,
"Diff": 0
},
"Tc": {
"20180207": 25.8093,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "3435076276275003494",
"Ph": "topsy twitter",
"Tp": "",
"Rq": 480,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 4,
"Diff": 0
},
"Tr": {
"20180207": 1.264,
"Diff": 0
},
"Tc": {
"20180207": 5.80176,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
}
],
"Amp": 0
},
...
}

Return values

Name	Value	Description
keywords	integer	number of keywords used to build this report
limit	integer	maximum number of results to return
offset	integer	use this parameter to specify how many results to skip before building a report
total	integer	number of results
lost	integer	number of lost URLs (URLs that ranked for at least one keyword from a given campaign on the start date of the selected period, but don't rank for any keyword from a given campaign on the end date of the selected period)
new	integer	number of new URLs (URLs that didn't rank for any keyword from a given campaign on the start date of the selected period, but rank for at least one keyword from a given campaign on the end date of the selected period)
data	array	list of URLs ranking for keywords from a given campaign
data -> Ur	string	an URL that ranks for keyword(s) from a given campaign
data -> Tp	string (can be “”, “new” or “lost”)	"new" - means that this URL didn't rank for any keyword from a given campaign on the start date of the selected period, but ranks for at least one keyword from a given campaign on the end date of the selected period. "lost" - means that this URL ranked for at least one keyword from a given campaign on the start date of the selected period, but doesn't rank for any keyword from a given campaign on the end date of the selected period.
data -> Dt	array	data on overall metrics for a given URL
data -> Dt -> YYYYMMDD	array	data on overall metrics for a given URL on a given date
data -> Dt -> YYYYMMDD -> Av	float	average position for a list of keywords given URL ranks for on a given date
data -> Dt -> YYYYMMDD -> Mc	integer	number of keywords given URL ranks for on a given date
data -> Dt -> YYYYMMDD -> Rq	integer	total volume for a list of keywords given URL ranks for on a given date
data -> Dt -> Diff	array	how values of overall metrics changed between the start and the end of the selected period
data -> Dt -> Diff -> Av	float	how average position for a list of keywords given URL ranks for changed between the start and the end of the selected period
data -> Dt -> Diff -> Mc	integer	how number of keywords given URL ranks for changed between the start and the end of the selected period
data -> Dt -> Diff -> Rq	integer	how total volume changed between the start and the end of the selected period
data -> Kw	array	list of keywords given URL ranks for
data -> Kw -> Ph	string	keyword given URL ranks for
data -> Kw -> Pi	string	keyword ID
data -> Kw -> Rq	integer	keyword volume
data -> Kw -> Tp	string (can be “”, “new” or “lost”)	"new" - means that this URL didn't rank for this keyword on the start date of the selected period, but ranks for this keyword on the end date of the selected period. "lost" - means that this URL ranked for this keyword on the start date of the selected period, but doesn't rank this keyword on the end date of the selected period.
data -> Kw -> Tg	array	keyword tags
data -> Kw -> Dt	array	data on overall metrics for a given pair: URL + keyword
data -> Kw -> Dt -> Diff	integer	how position of a given URL, that ranks for given keyword on a given date changed between the start and the end of the selected period
data -> Kw -> Lt	array	this array contains data on position type (organic or local map pack)
data -> Kw -> Lt -> YYYYMMDD	string (can be “org” or “geo”)	what type of position URL held on the given day; “org” - normal organic position, “geo” - position within local map pack

Adwords Landing Pages report

tracking_landing_pages_adwords

Price 1000 API units per line

This report lists all landing pages of selected domain for current tracking campaign. For each landing page all the keywords that this landing page ranks for are reported.

Request parameters

Name	Value	Description
key*	XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX	An identification key assigned to a user after subscribing to SEMrush that is available via Profile page
action*	report
type*	tracking_landing_pages_adwords	request type
url*	string	tracked URL or competitor URL (with mask)
date_begin	date in YYYYMMDD format	starting date of a selected period
date_end	date in YYYYMMDD format	end date of a selected period
display_tags	string	tags separated by the '\|' symbol
display_filter	string	filter for columns Ph, Nq, Cp
display_limit	integer	number of returned results
display_offset	integer	This parameter allows you to skip a specified number of lines before sending results
display_sort	ph_asc, ph_desc, {DOMAIN_N}_pos_asc, {DOMAIN_N}_pos_desc, {DOMAIN_N}_be_asc, {DOMAIN_N}_be_desc, {DOMAIN_N}_di_asc, {DOMAIN_N}_di_desc, cp_asc, cp_desc, nq_desc, nq_asc	report sortings
newlost_filter	new, lost	return only new or lost urls
linktype_filter	0 - Include local pack rankings in all reports. This is the default value. 1 - Show only local pack rankings in all reports 2 - Exclude local pack rankings from all reports	local pack filter

Fields marked by an asterisk (*) are required

Request example

GET /?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&action=report&type=tracking_landing_pages_adwords&display_sort=1_mc_desc&date_begin=20180207&date_end=20180207&display_limit=100&display_filter=&display_offset=0&display_tags=&url=semrush.com/blog&filter_url=&newlost_filter=&linktype_filter=0

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example


{
"total": 37,
"state": "0",
"limit": 100,
"offset": 0,
"new": 0,
"lost": 0,
"keywords": 107,
"Pc": {
"http": 0,
"https": 37
},
"data": {
"0": {
"Ur": "https://www.semrush.com/blog/topsy-is-dead-alternative-social-analytics-tools-you-need-to-use-now/",
"Tp": "",
"Dt": {
"20180207": {
"Mc": 9,
"Av": 2.22,
"Tr": 61.518333,
"Tc": 116.040433,
"Rq": 19620
},
"Diff": {
"Mc": 0,
"Av": 0,
"Tr": 0,
"Tc": 0,
"Rq": 0
}
},
"Kw": [
{
"Pi": "7922908393917093815",
"Ph": "topsy analytics",
"Tp": "",
"Rq": 320,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 1,
"Diff": 0
},
"Tr": {
"20180207": 3.882667,
"Diff": 0
},
"Tc": {
"20180207": 25.819733,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "1522738860508378941",
"Ph": "topsy com analytics",
"Tp": "",
"Rq": 170,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 1,
"Diff": 0
},
"Tr": {
"20180207": 2.062667,
"Diff": 0
},
"Tc": {
"20180207": 4.682253,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "3772292990852912364",
"Ph": "topsy social",
"Tp": "",
"Rq": 90,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 1,
"Diff": 0
},
"Tr": {
"20180207": 1.092,
"Diff": 0
},
"Tc": {
"20180207": 0,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "8747962949595138851",
"Ph": "topsy twitter analytics",
"Tp": "",
"Rq": 90,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 1,
"Diff": 0
},
"Tr": {
"20180207": 1.092,
"Diff": 0
},
"Tc": {
"20180207": 9.67512,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "9069259884330927019",
"Ph": "what is topsy com",
"Tp": "",
"Rq": 90,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 2,
"Diff": 0
},
"Tr": {
"20180207": 0.375,
"Diff": 0
},
"Tc": {
"20180207": 0,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "2019165307386841491",
"Ph": "topsy com",
"Tp": "",
"Rq": 5400,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 3,
"Diff": 0
},
"Tr": {
"20180207": 17.1,
"Diff": 0
},
"Tc": {
"20180207": 41.382,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "13769451381664187323",
"Ph": "topsy.com",
"Tp": "",
"Rq": 880,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 3,
"Diff": 0
},
"Tr": {
"20180207": 2.786667,
"Diff": 0
},
"Tc": {
"20180207": 2.870267,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "2409524746484837701",
"Ph": "topsy",
"Tp": "",
"Rq": 12100,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 4,
"Diff": 0
},
"Tr": {
"20180207": 31.863333,
"Diff": 0
},
"Tc": {
"20180207": 25.8093,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "3435076276275003494",
"Ph": "topsy twitter",
"Tp": "",
"Rq": 480,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 4,
"Diff": 0
},
"Tr": {
"20180207": 1.264,
"Diff": 0
},
"Tc": {
"20180207": 5.80176,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
}
],
"Amp": 0
},
...
}

Return values

Name	Value	Description
keywords	integer	number of keywords used to build this report
limit	integer	maximum number of results to return
offset	integer	use this parameter to specify how many results to skip before building a report
total	integer	number of results
lost	integer	number of lost URLs (URLs that ranked for at least one keyword from a given campaign on the start date of the selected period, but don't rank for any keyword from a given campaign on the end date of the selected period)
new	integer	number of new URLs (URLs that didn't rank for any keyword from a given campaign on the start date of the selected period, but rank for at least one keyword from a given campaign on the end date of the selected period)
data	array	list of URLs ranking for keywords from a given campaign
data -> Ur	string	an URL that ranks for keyword(s) from a given campaign
data -> Tp	string (can be “”, “new” or “lost”)	"new" - means that this URL didn't rank for any keyword from a given campaign on the start date of the selected period, but ranks for at least one keyword from a given campaign on the end date of the selected period. "lost" - means that this URL ranked for at least one keyword from a given campaign on the start date of the selected period, but doesn't rank for any keyword from a given campaign on the end date of the selected period.
data -> Dt	array	data on overall metrics for a given URL
data -> Dt -> YYYYMMDD	array	data on overall metrics for a given URL on a given date
data -> Dt -> YYYYMMDD -> Av	float	average position for a list of keywords given URL ranks for on a given date
data -> Dt -> YYYYMMDD -> Mc	integer	number of keywords given URL ranks for on a given date
data -> Dt -> YYYYMMDD -> Rq	integer	total volume for a list of keywords given URL ranks for on a given date
data -> Dt -> Diff	array	how values of overall metrics changed between the start and the end of the selected period
data -> Dt -> Diff -> Av	float	how average position for a list of keywords given URL ranks for changed between the start and the end of the selected period
data -> Dt -> Diff -> Mc	integer	how number of keywords given URL ranks for changed between the start and the end of the selected period
data -> Dt -> Diff -> Rq	integer	how total volume changed between the start and the end of the selected period
data -> Kw	array	list of keywords given URL ranks for
data -> Kw -> Ph	string	keyword given URL ranks for
data -> Kw -> Pi	string	keyword ID
data -> Kw -> Rq	integer	keyword volume
data -> Kw -> Tp	string (can be “”, “new” or “lost”)	"new" - means that this URL didn't rank for this keyword on the start date of the selected period, but ranks for this keyword on the end date of the selected period. "lost" - means that this URL ranked for this keyword on the start date of the selected period, but doesn't rank this keyword on the end date of the selected period.
data -> Kw -> Tg	array	keyword tags
data -> Kw -> Dt	array	data on overall metrics for a given pair: URL + keyword
data -> Kw -> Dt -> Diff	integer	how position of a given URL, that ranks for given keyword on a given date changed between the start and the end of the selected period
data -> Kw -> Lt	array	this array contains data on position type (organic or local map pack)
data -> Kw -> Lt -> YYYYMMDD	string (can be “org” or “geo”)	what type of position URL held on the given day; “org” - normal organic position, “geo” - position within local map pack

Sortings

Value	Description
ph_asc	sorting by a keyword in ascending order (Ph)
ph_desc	sorting by a keyword in descending order (Ph)
{DATE}_asc	sorting by date in ascending order
{DATE}_desc	sorting by date, in descending order
cp_asc	sorting by CPC in ascending order (Cp)
cp_desc	sorting by CPC in descending order (Cp)
nq_asc	sorting by volume in ascending order (Nq)
nq_desc	sorting by volume in descending order (Nq)
{DOMAIN_N}_di_asc	sorting by the difference in a domain's previous and current positions in ascending order
{DOMAIN_N}_di_desc	sorting by the difference in a domain's previous and current positions in descending order
{DOMAIN_N}_fi_asc, {DOMAIN_N}_pos_asc	sorting by a position at the end date in ascending order
{DOMAIN_N}_fi_desc, {DOMAIN_N}_pos_desc	sorting by a position at the end date in descending order
{DOMAIN_N}_be_asc	sorting by a position at the starting date in ascending order
{DOMAIN_N}_be_desc	sorting by a position at the starting date in ascending order
ur_asc	sorting by a URL in ascending order
ur_desc	sorting by a URL in descending order
cl_asc	sorting by visibility in ascending order
cl_desc	sorting by visibility in descending order
cd_asc	sorting by visibility change in ascending order
cd_desc	sorting by visibility change in descending order
av_asc	sorting by average position in ascending order
av_desc	sorting by average position in descending order

{DATE} date in YYYYMMDD format
{DOMAIN_N} - domain number (0,1,2,3,4)

Filters

To apply a filter to the report, you should add the display_filter parameter with an URL-encoded string that contains filters separated by "|" (maximum number - 25).

A filter consists of <sign>|<field>|<operation>|<value>

Parameter	Values	Description
sign	"+" or "-"	include or exclude
field	Ph, Cp, Nq	Ph - phrase Cp - Average price in U.S. dollars advertisers pay for a user’s click on an ad containing the given keyword (Google AdWords). Nq - The average number of times users have searched for a given keyword per month. We calculate this value over the last 12 months.
operation	for metrical fields: Eq, Gt, Lt for textual fields: Bw, Ew, Eq, Co	for metrical fields: Eq - exactly matching Gt - greater than Lt - less than for textual fields: Bw - starts with Ew - ends with Eq - exactly matching Co - containing
value	value to filter

Site Audit Tool

Management

The base URL for all requests is:

https://api.semrush.com/management/v1/projects/{ID}/siteaudit

Where {ID} - id of the project

Enable the Site Audit Tool

siteaudit_campaign_save

Price 100 API units per request

This request allows you to enable the Site Audit tool for a project, which will allow you to schedule audits, include or exclude pages from the crawl, and set the number of pages to crawl.

Requested URL (POST)

https://api.semrush.com/management/v1/projects/{ID}/siteaudit/enable?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Request parameters

Name	Value	Description
key*	String	An identification key assigned to a user after subscribing to SEMrush that is available via Profile page

Fields marked by an asterisk (*) are required

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Request example

{
"domain": "www.mysite.com",
"scheduleDay": 1,
"notify": false,
"allow": ["", "", ""],
"disallow": ["", "", ""],
"pageLimit": 1000,
"userAgentType": 2,
"removedParameters": ["", "", ""]
"crawlSubdomains": true,
"respectCrawlDelay": false
}

Request parameters

domain	Project URL
scheduleDay	run periodically day(1..7) if 0 - manual start
notify	Email notification about the finished audit
allow	Mask ALLOW in this project
disallow	Mask DISALLOW in this project
pageLimit	Number of crawled page
userAgentType	Type of user agent. Available values: 0 - SEMrushBot Desktop 1 - SEMrushBot Mobile 2 - GoogleBot Desktop 3 - GoogleBot Mobile
removedParameters	Specifies URL parameters to be excluded from the audit scope
crawlSubdomains	Specifies whether to crawl subdomains of the selected domain. Available values: true - SEMrushBot will crawl the selected domain, including its subdomains false - SEMrushBot will crawl the selected domain, excluding its subdomains
respectCrawlDelay	Specifies whether SEMrushBot should follow the “crawl-delay” directive in robots.txt. Available values: true - SEMrushBot will follow the “crawl-delay” directive in robots.txt false - SEMrushBot will crawl pages with an interval of 1 second

Edit a campaign

siteaudit_campaign_save

Price 100 API units per request

This request allows you to edit an existing Site Audit’s campaign, which will allow you to re-schedule audits, change the scope of pages to crawl and the number of pages.

Requested URL (POST)

https://api.semrush.com/management/v1/projects/{ID}/siteaudit/save?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Request parameters

Name	Value	Description
key*	String	An identification key assigned to a user after subscribing to SEMrush that is available via Profile page

Fields marked by an asterisk (*) are required

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Request example

{
"domain": "www.mysite.com",
"scheduleDay": 1,
"notify": false,
"allow": ["", "", ""],
"disallow": ["", "", ""],
"pageLimit": 1000,
"userAgentType": 2,
"removedParameters": ["", "", ""]
"crawlSubdomains": true,
"respectCrawlDelay": false
}

Request parameters

domain	Project URL
scheduleDay	run periodically day(1..7) if 0 - manual start
notify	Email notification about the finished audit
allow	Mask ALLOW in this project
disallow	Mask DISALLOW in this project
pageLimit	Number of crawled page
userAgentType	Type of user agent. Available values: 0 - SEMrushBot Desktop 1 - SEMrushBot Mobile 2 - GoogleBot Desktop 3 - GoogleBot Mobile
removedParameters	Specifies URL parameters to be excluded from the audit scope
crawlSubdomains	Specifies whether to crawl subdomains of the selected domain. Available values: true - SEMrushBot will crawl the selected domain, including its subdomains false - SEMrushBot will crawl the selected domain, excluding its subdomains
respectCrawlDelay	Specifies whether SEMrushBot should follow the “crawl-delay” directive in robots.txt. Available values: true - SEMrushBot will follow the “crawl-delay” directive in robots.txt false - SEMrushBot will crawl pages with an interval of 1 second

Reports

The base URL for all requests is:

https://api.semrush.com/reports/v1/projects/{ID}/siteaudit

Where {ID} - id of the project

Get a list of a campaign's snapshots

siteaudit_snapshot_list

Price 100 API units per request

This request allows you to get a list of past audits' IDs, including the dates on which they were completed.

Requested URL (GET)

https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/snapshots?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Request parameters

Name	Value	Description
key*	String	An identification key assigned to a user after subscribing to SEMrush that is available via Profile page

Fields marked by an asterisk (*) are required

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example

{
"snapshots":[
{
"snapshot_id":"540d9e420cf2e0c1006966e3",
"finish_date":1410178856809
},
{
"snapshot_id":"54102bd20cf2e0c100696a10",
"finish_date":1410345954754
}]
}

Response parameters

snapshot_id	Snapshot id
finish_date	Date when the last audit finished

Get text descriptions about issues

siteaudit_meta

Price 100 API units per request

This request allows you to get a description of why an issue could be harmful for a website and how it can be fixed.

Requested URL (GET)

https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/meta/issues?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Request parameters

Name	Value	Description
key*	String	An identification key assigned to a user after subscribing to SEMrush that is available via Profile page

Fields marked by an asterisk (*) are required

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example


{
"issues":[
{
"id":1,
"title":"HTTP 5XX server errors",
"desc":"5xx errors happen on the server’s side. (500 – an internal server error; 503 – a server is unavailable; 507 – a server is running out of memory, etc.) \n\nHaving a lot of error pages negatively affects both User Experience and a search engine robot’s crawlability, which can lead to less traffic to your website.",
"title_page":"##count## pages returned 5XX status code upon request",
"title_detailed":"This page returned 5XX status code on request",
"info_column":"Code",
"count_description":"This page returned 5XX status code on request",
"multidata":false,
"other_problem_link":"##count## more page on this site has 500 status code",
"desc_with_link":" ##count## pages  returned 5XX status code upon request"
}]
}

Response parameters

id	Issue id
title	Issue Title
desc	Issue Description
title_page	Page Title
info_column	-
count_description	-
multidata	-
other_problem_link	-
desc_with_link	-

Run Audit

siteaudit_launch

Price 100 API units per request

This request allows you to run an audit.

Requested URL (POST)

https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/launch?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Request parameters

Name	Value	Description
key*		An identification key assigned to a user after subscribing to SEMrush that is available via Profile page

Fields marked by an asterisk (*) are required

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example


{
"snapshot_id":"54102d92e4b0f889a040c9c8"
}

Response parameters

snapshot_id

Snapshot ID for this audit

Get information about a campaign

siteaudit_campaign_info

Price 100 API units per request

This request allows you to get an overview of the last audit, including the number of found issues errors, warnings, and notices, the number of passed and failed checks, the number of crawled pages and the rest of pages to crawl, and the date of the last audit, etc.

Requested URL (GET)

https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/info?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Request parameters

Name	Value	Description
key*	String	An identification key assigned to a user after subscribing to SEMrush that is available via Profile page

Fields marked by an asterisk (*) are required

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example

{
"id":4594705336925861,
"name":"test",
"url":"semrush.com",
"status":"FINISHED",
"errors":228,
"warnings":391,
"notices":9,
"broken":0,
"blocked":0,
"redirected":2,
"healthy":1,
"haveIssues":2,
"haveIssuesDelta":0,
"defects":{"109":2},
"markups":{
"twitterCard":0,
"openGraph":0,
"schemaOrg":0,
"microfomats":0
},
"depths":{"0":3},
"crawlSubdomains":true,
"respectCrawlDelay":false,
"canonical":0,
"user_agent_type":2,
"last_audit":1410346398040,
"last_failed_audit":0,
"next_audit":-1,
"running_pages_crawled":178,
"running_pages_limit":500,
"pages_crawled":178,
"pages_limit":500,
"total_checks":22725,
"errors_delta":0,
"warnings_delta":0,
"notices_delta":0,
"mask_allow":[],
"mask_disallow":[],
"removedParameters":["rr","r","p"],
"excluded_checks":null
}

Response parameters

id	Project ID
url	Project URL
name	Project name
status	Audit’s status: Running, Finished, Checking, or Saving
errors	Number of errors found during the last audit
warnings	Number of warnings found during the last audit
notices	Number of notices found during the last audit
broken	Number of broken pages
blocked	Number of pages blocked from crawling
redirected	Number of redirecting pages
healthy	Number of healthy pages
haveIssues	Number of pages with issues
haveIssuesDelta	Difference in the number of issues found during the previous and last audits
defects	List of issue IDs detected on crawled pages and the number of times each issue was detected
markups	Number of markups detected on crawled pages. Supported markups are: Twitter Card, Open Graph, Schema.org, microfomats
depths	Number of clicks required for SEMrushBot to reach an analyzed page from the homepage
crawlSubdomains	Indicates whether SEMrushBot crawled subdomains of the selected of the analyzed domain: true - SEMrushBot crawled the analyzed domain, including its subdomains false - SEMrushBot crawled the analyzed domain, excluding its subdomains
respectCrawlDelay	Indicates whether SEMrushBot followed the “crawl-delay” directive in robots.txt: true - SEMrushBot followed the “crawl-delay” directive in robots.txt false - SEMrushBot crawled pages with an interval of 1 second
canonical	Indicates whether an analyzed page is marked with the rel=“canonical” link element
user_agent_type	Type of user agent: 0 - SEMRushBot Desktop 1 - SEMRushBot Mobile 2 - GoogleBot Desktop 3 - GoogleBot Mobile
last_audit	Date of the last audit
last_failed_audit	Date of the last site audit failure
next_audit	Date of next scheduled audit
running_pages_crawled	Number of pages crawled during the running audit
running_pages_limit	Crawled pages' limit for the running audit
pages_crawled	Number of crawled pages
pages_limit	Crawled pages limit
total_checks	Total checks made during the last audit
errors_delta	Difference in the number of errors found during the previous and last audits
warnings_delta	Difference in the number of warnings found during the previous and last audits
notices_delta	Difference in the number of notices found during the previous and last audits
mask_allow	Mask ALLOW in this project
mask_disallow	Mask DISALLOW in this project
removedParameters	URL parameters excluded from the audit scope
excluded_checks	IDs of issues (errors, warnings and notices) excluded from the audit scope

Get information about a snapshot

siteaudit_snapshot_info

Price 10000 API units per request

This request allows you to get an overview of an audit, including the website’s score, issues, its number of performed checks, etc.

Requested URL (GET)

https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/snapshot?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&snapshot_id={snapshot_id}

Request parameters

Name	Value	Description
key*		An identification key assigned to a user after subscribing to SEMrush that is available via Profile page
snapshot_id	String	Snaphot Id, or latest snapshot

Fields marked by an asterisk (*) are required

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example

{
"quality":{
"value":42,
"delta":0
},
"errors":[
{
"id":1,
"count":4,
"delta":0,
"checks":174
},
],
"warnings":[
{
"id":101,
"count":2,
"delta":0,
"checks":127
},
],
"notices":[
{
"id":201,
"count":1,
"delta":0,
"checks":127
},
],
"snapshot_id":"54102d92e4b0f889a040c9c8",
"pages_crawled":178,
"finish_date":1410346398040
}

Response parameters

quality.value	Website's score
quality.delta	Difference in scores a website received during the previous and last audits
snapshot_id	Snapshot ID
pages_crawled	Crawled pages
finish_date	Date when the last audit finished
warnings\|errors\|notices.id	Issue ID
warnings\|errors\|notices.count	Number of found issues
warnings\|errors\|notices.delta	Difference in the number of issues found during the previous and last audits
warnings\|errors\|notices.checks	the number of performed checks for errors, warnings, or notices

Detailed report for an issue

siteaudit_snapshot_issue

Price 100 API units per request or 100 API units by one issue

This report provides a description of an issue, the date when this issue was detected, and lists of affected webpages’ URLS.

Requested URL (GET)

https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/snapshot/{snapshotId}/issue/{issueId}?page={page}&filter={filter}&sort={sort}&limit={limit}&key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Request parameters

Name	Value	Description
key*	String	An identification key assigned to a user after subscribing to SEMrush that is available via Profile page
snapshotId*	String	Snapshot Id
issueId*	integer	Issue Id
page	integer default 1	Pagination
filter		Filter data
limit	integer default 10	limit data line
sort	index_desc, index_asc, firstseen_desc, firstseen_asc	Sorting

Fields marked by an asterisk (*) are required

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example

{
"limit":10,
"page":1,
"total":101,
"data":[
{
"title":"Web Tutorials • Mike & Associates",
"info":"404",
"first_seen":1410178856809,
"last_seen":1410346398040,
"target_url":"http://semrush.com/errors/404.html",
"page_id":"54102d9e0cf2e0c100696c88",
"source_url":"http://semrush.com"
},
],
"issue_id":8
}

Response parameters

Date when an issue was first noticed

limit	Limit result on one page
page	Page number
total	Total number of results per request
issue_id	Issue ID
title	The title of a page on which an error has been detected
info	Issue's description
first_seen	first seen
last_seen	Date when an issue was last noticed
target_url	Target URL (for example, for a broken link issue, a URL of a webpage returning an error status will be shown)
page_id	Page ID
source_url	The URL of a webpage on which an error has been detected

Get page ID by an URL

siteaudit_page_list

Price 100 API units per request

This request helps you get an ID of a crawled page.

Requested URL (GET)

https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/page/list?url_contains={url}&limit={limit}&key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Request parameters

Name	Value	Description
key*	String	An identification key assigned to a user after subscribing to SEMrush that is available via Profile page
url*	String	url for search(contains match)
limit	integer default 10	limit data line

Fields marked by an asterisk (*) are required

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example

{
"data":[
{
"url":"http://semrush.com",
"page_id":"54102d9e0cf2e0c100696c88"
},
],
"total":178
}

Response parameters

url	url
page_id	page id
total	Total number of results per request

Get information about a page

siteaudit_page_info

Price 1000 API units per request

This request allows you to get information about a page, and to get a list of its issues.

Requested URL (GET)

https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/page/{pageId}?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Request parameters

Name	Value	Description
key*	String	An identification key assigned to a user after subscribing to SEMrush that is available via Profile page
pageId*	String	page ID

Fields marked by an asterisk (*) are required

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example

{
"weight":0,
"title":"Web Tutorials • Mike & Associates",
"url":"http://semrush.com",
"notices":[
{
"id":202,
"data":[
{
"discovered":1410178856809,
"info":null,
"target_url":"http://%/test.com"
}
],
"total":8
}
],
"warnings":[
{
"id":110,
"data":[
{
"discovered":1410178856809,
"info":null,
"target_url":"http://semrush.com/index_files/html.jpg"
},
],
"total":200
}
],
"errors":[
{
"id":8,
"data":[
{
"discovered":1410178856809,
"info":"503",
"target_url":"http://semrush.com/errors/503.html"
},
],
"total":101
},
],
"page_id":"54102d9e0cf2e0c100696c88"
}

Response parameters

weight	This page's weight
title	This page's title
url	URL
notices\|warnings\|errors.id	Issue ID
notices\|warnings\|errors.discovered	Date when an issue was first noticed
notices\|warnings\|errors.info	Issue's description
notices\|warnings\|errors.target_url	Target URL (for example, for a broken link issue, a URL of a webpage returning an error status will be shown)
notices\|warnings\|errors.total	Total Issues
page_id	Page ID

Get snaphots history

siteaudit_campaign_history

Price 10000 API units per request or 10000 API units by one snapshot

This request allows you to see audits’ results for a selected period.

Requested URL (GET)

https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/history?limit={limit}&offset={offset}&key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Request parameters

Name	Value	Description
key*	String	An identification key assigned to a user after subscribing to SEMrush that is available via Profile page
limit*	Integer default 7	limit
offset*	Integer default 0	offset

Fields marked by an asterisk (*) are required

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example

{
"data":[
{
"quality":{
"value":42,
"delta":0
},
"errors":[
{
"id":1,
"count":4,
"delta":0,
"checks":174
},
],
"warnings":[
{
"id":101,
"count":2,
"delta":0,
"checks":127
},
],
"notices":[
{
"id":201,
"count":1,
"delta":0,
"checks":127
},
],
"snapshot_id":"54102d92e4b0f889a040c9c8",
"pages_crawled":178,
"finish_date":1410346398040
},
],
"total":0,
"limit":0,
"offset":0
}

Response parameters

quality.value	Website's score
quality.delta	Difference in scores a website received during the previous and last audits
snapshot_id	Snapshot ID
pages_crawled	Crawled pages
finish_date	Date when the last audit finished
warnings\|errors\|notices.id	Issue ID
warnings\|errors\|notices.count	Number of found issues
warnings\|errors\|notices.delta	Difference in the number of issues found during the previous and last audits
warnings\|errors\|notices.checks	the number of performed checks for errors, warnings, or notices

Price in API units

$1 = 20,000 API units. View SEMrush API packages ›

Prices are displayed for such request types as lines, calls, and keywords.

Type	Description	Cost in API units
Type	Description	per line	per call	per keyword
project_list	List all existing projects	—	100	—
project_get	Get information about an existing project	—	100	—
project_create	Create a new project	—	100	100*
project_update	Update an existing project	—	100	100*
project_delete	Delete an existing project	—	100	—
project_add_keywords	Add keywords to an existing project	—	—	100
project_delete_keywords	Remove keywords from an existing project	—	100	—
project_add_competitors	Add competitors to an existing project	—	100	—
project_delete_competitors	Remove competitors from an existing project	—	100	—
project_add_tags	Group keywords with tags in an existing project	—	100	—
project_remove_tags	Remove tags from keywords in an existing project	—	100	—
tracking_overview_organic	Organic Overview	—	100	—
tracking_visibility_organic	Organic Visibility Index report	—	100	—
tracking_visibility_adwords	AdWords Visibility Index report	—	100	—
tracking_position_organic	Organic Positions report	100	—	—
tracking_position_adwords	AdWords Positions report	100	—	—
tracking_competitors_organic	Organic Competitors Discovery report	1000	—	—
tracking_competitors_adwords	AdWords Competitors Discovery report	1000	—	—
tracking_landing_pages_organic	Organic Landing Pages report	1000	—	—
tracking_landing_pages_adwords	Adwords Landing Pages report	1000	—	—
tracking_campaign_dates	Campaign Dates	—	100	—
tracking_enable	Enable the Position Tracking Tool in a project	—	100	—
tracking_notification_update	Enable/Disable email-sending containing project statistics	—	100	—
get_countries	Get a list of countries	—	100	—
get_regions	Get a list of regions	—	100	—
get_cities	Get a list of cities	—	100	—
siteaudit_snapshot_list	Get a list of a campaign's snapshots	—	100	—
siteaudit_meta	Get text descriptions about issues	—	100	—
siteaudit_launch	Run Audit	—	100	—
siteaudit_campaign_info	Get information about a campaign	—	100	—
siteaudit_campaign_save	Enable the Site Audit Tool	—	100	—
siteaudit_snapshot_info	Get information about a snapshot	—	10000	—
siteaudit_snapshot_issue	Detailed report for an issue	100	100	—
siteaudit_page_list	Get page ID by an URL	—	100	—
siteaudit_page_info	Get information about a page	—	1000	—
siteaudit_campaign_history	Get snaphots history	10000**	10000	—

* The additional API units are charged for each new added keyword.
** By Snapshots

Error Messages

Projects API error messages are returned in a specific format:

{
"code": {ERROR_CODE},
"message": {ERROR_MESSAGE}
}

ERROR_CODE	integer	Machine-parseable codes
ERROR_MESSAGE	string	Descriptive error text

In addition to descriptive error text, error messages contain machine-parsable codes. While the text for an error message may change, the codes will stay the same. The following table describes the codes that may appear when working with the API:

ERROR_CODE	ERROR_MESSAGE
511	Unknown error
512	Can't find project with project_id {ID}
513	Invalid tool_id
515	Campaign already exists
519	Missing mandatory URL parameter
520	Invalid tag name
521	Projects limit exceed, projects created: {projects_count}, user limit are {projects_limit}
522	Keywords limit exceed, keywords limit {keywords_limit} already tracked keywords {keywords_count}
70	API key hash failure
120	Wrong key - ID pair
121	Wrong format or empty hash
122	Wrong format or empty key
130	Api disabled
131	Limit exceeded
132	API units balance is zero
134	Total limit exceeded

SEMrush API 3.0

Projects API

Endpoint

Requested URL (GET)

Request parameters

Response

Response example

Response parameters

Requested URL (GET)

Request parameters

Response

Response example

Response parameters

Requested URL (POST)

Request parameters

Request example

Response

Response example

Response parameters

Requested URL (PUT)

Request parameters

Request example

Response

Response example

Response parameters

Requested URL (DELETE)

Request parameters

Response

Requested URL (PUT)

Request parameters

Request example

Response

Response example

Response parameters

Requested URL (DELETE)

Request parameters

Request example

Response

Response example

Response parameters

Requested URL (PUT)

Request parameters

Request example

Response

Response example

Response parameters

Requested URL (DELETE)

Request parameters

Request example

Response

Response example

Response parameters

Requested URL (PUT)

Request parameters

Request example

Response

Response example

Response parameters

Requested URL (DELETE)

Request parameters

Request example

Response

Response example

Response parameters

Request parameters

Request example

Response

Request parameters

Request example

Response

Request parameters

Request example

Response

Response example

Return values

Request parameters

Request example

Response

Response example

Return values

SEMrush API
3.0