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} - method name.

Enable the Position Tracking Tool in a project

tracking_enable

Price 100 API units per request

This request enables the Position Tracking tool in a project to get daily updates on keywords rankings for the project domain and its competitors.

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*	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 (default) 0	1 - enable weekly emails 0 - disable weekly emails
first_letter	1 (default) 0	1 - send an email when the first harvesting is finished for the project 0 - do not send an email when the first harvesting is finished for the project
timezone	integer	Time zone (crawling starts at 5am in a specified time zone)
device	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 the tracking_enable request is country_id. The following requests return a list of available countries and their corresponding regions and cities.

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 returns a list of IDs of the countries a project can be set up for.

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 returns a list of regions within the specified country that a project can be set up for.

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 returns a list of cities within the specified country and region that a project can be set up for.

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 of the report requests use the HTTP GET method.
The base URL for all requests is:

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

Where {ID} - id of the project.

Attention! In 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 it 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 harvested.

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	The number of results
last_crawl	integer	Hours elapsed since the last crawl
Dt	Date in YYYYMMDD format	Date

Organic Overview

tracking_overview_organic

Price 100 API units per request

This request returns the number of keywords that land the specified domain on each of the top 100 positions on SERP, the number of new and lost keywords, the number of keywords with improved or decreased rankings, and the number of keywords that have changed their rankings over the 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. The '-' sign can be used to exclude a tag. If only the included tags are present in the expression, then the OR logic is used to group them. If both included and excluded tags are present, then each category is grouped using the OR logic, but then the AND logic is used to join the categories
date_begin	Date in YYYYMMDD format	Start date of the selected period
date_end	Date in YYYYMMDD format	End date of the selected period
linktype_filter	0 - Include local pack and hotels rankings. This is the default value 1 - Include only local pack and hotels rankings (organic rankings are excluded) 2 - Exclude local pack rankings 524288 - Exclude hotels rankings 524290 - Exclude local pack and hotels rankings	Specifies whether the local pack and hotels rankings should be included in the report output or excluded from it
business_name	string	The business name associated with the domain. It should match that from the Google My Business profile

Fields marked by an asterisk (*) are required

Request example

GET /?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&action=report&type=tracking_overview_organic&url=*.apple.com%2F*&date_begin=20140405&date_end=20140411&linktype_filter=0&display_tags=tag1|tag2

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": {
			0: 47,
			1: 17,
			2: 2,
			...
			99: 0
	}
}

Return values

Name	Value	Description
total	integer	The number of results
visibility	percentage	The visibility index
differenceVisibility	percentage	The visibility index difference
all	integer	The number of keywords ranking in the top 100
all_difference	integer	The difference in the number of keywords ranking in the top 100
all_improved	integer	The number of improved keywords in the top 100
all_declined	integer	The number of declined keywords in the top 100
all_left	integer	The number of keywords that no longer rank in the top 100
all_entered	integer	The number of keywords that have entered the top 100
top3	integer	The number of keywords ranking in the top 3
top3_improved	integer	The number of improved keywords in the top 3
top3_declined	integer	The number of declined keywords in the top 3
top3_difference	integer	The difference in the number of keywords ranking in the top 3
top3_left	integer	The number of keywords that no longer rank in the top 3
top3_entered	integer	The number of keywords that have entered the top 3
top10	integer	The number of keywords ranking on the first page of search results
top10_improved	integer	The number of improved keywords ranking on the first page of search results
top10_declined	integer	The number of declined keywords ranking on the first page of search results
top10_difference	integer	The difference in the number of keywords ranking on the first page of search results
top10_left	integer	The number of keywords that no longer rank on the first page of search results
top10_entered	integer	The number of keywords that have entered the first page of search results
top20	integer	The number of keywords ranking on the first two pages of search results
top20_improved	integer	The number of improved keywords ranking on the first two pages of search results
top20_declined	integer	The number of declined keywords ranking on the first two pages of search results
top20_difference	integer	The difference in the number of keywords ranking on the first two pages of search results
top20_left	integer	The number of keywords that no longer rank on the first two pages of search results
top20_entered	integer	The number of keywords that have entered the first two pages of search results
data	array	An array of SERP positions (where 0 stands for SERP #1 position and 99 stands for SERP #100 position) and numbers of keywords on this position on SERP for the end date of the selected period

Organic Positions report

tracking_position_organic

Price 100 API units per line

This request lists all keywords from a tracking campaign, the Google’s top 100 rankings of the specified URLs for these keywords, and position changes over the 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	A list of encoded URLs (with mask), separated by ":"
date_begin	Date in YYYYMMDD format	Start date of the selected period
date_end	Date in YYYYMMDD format	End date of the selected period
display_tags	string	Tags, separated by the '\|' symbol. The '-' sign can be used to exclude a tag. If only the included tags are present in the expression, then the OR logic is used to group them. If both included and excluded tags are present, then each category is grouped using the OR logic, but then the AND logic is used to join the categories
display_filter	string	Filter for columns Ph, Nq, Cp
display_limit	integer	The number of returned results, the default value is 10
display_offset	integer	The number of lines to skip in the report output
display_sort	cp_asc cp_desc {DOMAIN_N}_be_asc {DOMAIN_N}_be_desc {DOMAIN_N}_di_asc {DOMAIN_N}_di_desc {DOMAIN_N}_pos_asc {DOMAIN_N}_pos_desc nq_asc nq_desc ph_asc ph_desc	Report sorting
linktype_filter	0 - Include local pack and hotels rankings. This is the default value 1 - Include only local pack and hotels rankings (organic rankings are excluded) 2 - Exclude local pack rankings 524288 - Exclude hotels rankings 524290 - Exclude local pack and hotels rankings	Specifies whether the local pack and hotels rankings should be included in the report output or excluded from it
use_volume	national regional local	Specifies the level of CPC and volume to be used in the report. If omitted, the bottom-most available level is used
business_name	string	The business name associated with the domain. It should match that from the Google My Business profile
serp_feature_filter	fsn: Featured snippet geo: Local pack hot: Hotels kng: Knowledge panel rev: Reviews amp: AMP stl: Site links vid: Video vib: Featured video new: Top stories rel: People also ask img: Images twt: Twitter knw: Instant answer flg: Flights shp: Shopping ads adt: AdWords top adb: AdWords bottom	Filters the report output for keywords that have a specific SERP feature on SERP

Fields marked by an asterisk (*) are required

Request example

GET /?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&action=report&type=tracking_position_organic&url=*.apple.com%2F*:*.amazon.com%2F*&date_begin=20210521&date_end=20210527&linktype_filter=0&display_tags=tag1|tag2&display_sort=0_pos_asc

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example


{
    "total": 2,
    "state": "0",
    "limit": 10,
    "offset": 0,
    "data": {
        "0": {
            "Pi": "801444466689038445",
            "Ph": "facebook",
            "Kb": 20170908,
            "Tg": {
                "0": "tag1"
            },
            "Cp": "1.44",
            "Nq": "185000000",
            "Gs": "0",
            "Dt": {
                "20210521": {
                    "*.apple.com/*": 4,
                    "*.amazon.com/*": 32
                },
                ...
                "20210527": {
                    "*.apple.com/*": 3,
                    "*.amazon.com/*": 38
                }
            },
            "Be": {
                "*.apple.com/*": 4,
                "*.amazon.com/*": 32
            },
            "Fi": {
                "*.apple.com/*": 3,
                "*.amazon.com/*": 38
            },
            "Diff": {
                "*.apple.com/*": 1,
                "*.amazon.com/*": -6
            },
            "Diff1": {
                "*.apple.com/*": 0,
                "*.amazon.com/*": -10
            },
            "Diff7": {
                "*.apple.com/*": 97,
                "*.amazon.com/*": 62
            },
            "Diff30": {
                "*.apple.com/*": 97,
                "*.amazon.com/*": 62
            },
            "Vi": {
                "20210521": {
                    "*.apple.com/*": 10.851599999999999,
                    "*.amazon.com/*": 1.0713999999999999
                },
                ...
                "20210527": {
                    "*.apple.com/*": 13.0494,
                    "*.amazon.com/*": 0.90649999999999997
                },
                "Diff": {
                    "*.apple.com/*": 2.1978,
                    "*.amazon.com/*": -0.16489999999999999
                }
            },
            "Sf": {
                "20210521": [
                    "new",
                    "twt",
                    "rev",
                    "stl",
                    "kng"
                ],
                ...
                "20210527": [
                    "new",
                    "twt",
                    "rev",
                    "stl",
                    "kng"
                ]
            },
            "Tr": {
                "20210521": {
                    "*.apple.com/*": 487166.65999999997,
                    "*.amazon.com/*": 48100
                },
                ...
                "20210527": {
                    "*.apple.com/*": 585833.32999999996,
                    "*.amazon.com/*": 40700
                }
            },
            "Tc": {
                "20210521": {
                    "*.apple.com/*": 701520,
                    "*.amazon.com/*": 69264
                },
                ...
                "20210527": {
                    "*.apple.com/*": 843600,
                    "*.amazon.com/*": 58608
                }
            },
            "Lu": {
                "20210521": {
                    "*.apple.com/*": "https://apps.apple.com/us/app/facebook/id284882215",
                    "*.amazon.com/*": "https://www.amazon.com/Facebook/dp/B0094BB4TW"
                },
                ...
                "20210527": {
                    "*.apple.com/*": "https://apps.apple.com/us/app/facebook/id284882215",
                    "*.amazon.com/*": "https://www.amazon.com/Facebook/dp/B0094BB4TW"
                }
            },
            "Lt": {
                "20210521": {
                    "*.apple.com/*": [
                        "rev"
                    ],
                    "*.amazon.com/*": [
                        "rev"
                    ]
                },
                ...
                "20210527": {
                    "*.apple.com/*": [
                        "rev"
                    ],
                    "*.amazon.com/*": [
                        "rev"
                    ]
                }
            }
        },
	...
}

Return values

Name	Value	Description
total	integer	The number of results
limit	integer	The number of returned results
offset	integer	The number of lines to skip in the report output
data	array	An array of keywords and their metrics
Pi	string	Keyword ID
Ph	string	Keyword
Kb	string	The date the keyword was added to the tracking campaign
Tg	array	Keyword tags
Cp	float	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.
Gs	integer	Volume crawling status; 0 - crawled, 1 - not crawled
Dt	array	An array of dates and positions (dates in format "YYYYMMDD")
Be	array	Ranking at the beginning of the specified period
Fi	array	Ranking at the end of the specified period
Diff	array	The difference in rankings over the specified period
Diff1	array	The difference in rankings compared to the previous day
Diff7	array	The difference in rankings over a one week period
Diff30	array	The difference in rankings over a one month period
Vi	array	Domain's visibility on the specified date
Sf	array	Serp features present on SERP for the specified date
Tr	array	Estimated traffic on the specified date
Tc	array	Estimated traffic cost on the specified date
Lu	array	Landing URLs
Lt	array	Ranking type org: Organic fsn: Featured snippet geo: Local pack hot: Hotels kng: Knowledge panel rev: Reviews amp: AMP stl: Site links vid: Video vib: Featured video new: Top stories rel: People also ask img: Images twt: Twitter knw: Instant answer flg: Flights shp: Shopping ads adt: AdWords top adb: AdWords bottom

AdWords Positions report

tracking_position_adwords

Price 100 API units per line

This request lists all keywords from a tracking campaign, the Google’s paid search rankings of the specified URLs for these keywords, and position changes over the 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	A list of encoded URLs (with mask), separated by ":"
date_begin	Date in YYYYMMDD format	Start date of the selected period
date_end	Date in YYYYMMDD format	End date of the selected period
display_tags	string	Tags, separated by the '\|' symbol. The '-' sign can be used to exclude a tag. If only the included tags are present in the expression, then the OR logic is used to group them. If both included and excluded tags are present, then each category is grouped using the OR logic, but then the AND logic is used to join the categories
display_filter	string	Filter for columns Ph, Nq, Cp
display_limit	integer	The number of returned results, the default value is 10
display_offset	integer	The number of lines to skip in the report output
display_sort	cp_asc cp_desc {DOMAIN_N}_be_asc {DOMAIN_N}_be_desc {DOMAIN_N}_di_asc {DOMAIN_N}_di_desc {DOMAIN_N}_pos_asc {DOMAIN_N}_pos_desc nq_asc nq_desc ph_asc ph_desc	Report sorting

Fields marked by an asterisk (*) are required

Request example

GET /?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&action=report&type=tracking_position_adwords&url=*.apple.com%2F*:*.walmart.com%2F*&date_begin=20210522&date_end=20210528&display_sort=0_pos_asc&display_tags=tag1|tag2

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example


{
    "total": 4,
    "state": "0",
    "limit": 10,
    "offset": 0,
    "data": {
        "0": {
            "Pi": "5331787400075558242",
            "Ph": "appl",
            "Kb": 20170908,
            "Tg": {
                "0": "tag2"
            },
            "Cp": "1.00",
            "Nq": "165000",
            "Gs": "0",
            "Dt": {
                "20210522": {
                    "*.apple.com/*": "-",
                    "*.walmart.com/*": "-"
                },
                ...
                "20210528": {
                    "*.apple.com/*": 1,
                    "*.walmart.com/*": "-"
                }
            },
            "Be": {
                "*.apple.com/*": "-",
                "*.walmart.com/*": "-"
            },
            "Fi": {
                "*.apple.com/*": 1,
                "*.walmart.com/*": "-"
            },
            "Diff": {
                "*.apple.com/*": 11,
                "*.walmart.com/*": "-"
            },
            "Diff1": {
                "*.apple.com/*": 0,
                "*.walmart.com/*": "-"
            },
            "Diff7": {
                "*.apple.com/*": 11,
                "*.walmart.com/*": "-"
            },
            "Diff30": {
                "*.apple.com/*": 11,
                "*.walmart.com/*": "-"
            },
            "Vi": {
                "20210522": {
                    "*.apple.com/*": 0,
                    "*.walmart.com/*": 0
                },
                ...
                "20210528": {
                    "*.apple.com/*": 25,
                    "*.walmart.com/*": 0
                },
                "Diff": {
                    "*.apple.com/*": 25,
                    "*.walmart.com/*": 0
                }
            },
            "Sf": {
                "20210522": [
                    "new",
                    "knw",
                    "stl",
                    "kng"
                ],
                ...
                "20210528": [
                    "new",
                    "rel",
                    "adt",
                    "knw",
                    "rev",
                    "stl",
                    "kng"
                ]
            },
            "Tr": {
                "20210522": {
                    "*.apple.com/*": 0,
                    "*.walmart.com/*": 0
                },
                ...
                "20210528": {
                    "*.apple.com/*": 5500,
                    "*.walmart.com/*": 0
                }
            },
            "Tc": {
                "20210522": {
                    "*.apple.com/*": 0,
                    "*.walmart.com/*": 0
                },
                ...
                "20210528": {
                    "*.apple.com/*": 5500,
                    "*.walmart.com/*": 0
                }
            },
            "Lu": {
                "20210522": {
                    "*.apple.com/*": "",
                    "*.walmart.com/*": ""
                },
                ...
                "20210528": {
                    "*.apple.com/*": "https://www.apple.com/",
                    "*.walmart.com/*": ""
                }
            },
            "Lt": {
                "20210522": {
                    "*.apple.com/*": [
                        "org"
                    ],
                    "*.walmart.com/*": [
                        "org"
                    ]
                },
                ...
                "20210528": {
                    "*.apple.com/*": [
                        "adt"
                    ],
                    "*.walmart.com/*": [
                        "org"
                    ]
                }
            }
        },
	}
}

Return values

Name	Value	Description
total	integer	The number of results
limit	integer	The number of returned results
offset	integer	The number of lines to skip in the report output
data	array	An array of keywords and their metrics
Pi	string	Keyword ID
Ph	string	Keyword
Kb	string	The date the keyword was added to the tracking campaign
Tg	array	Keyword tags
Cp	float	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.
Gs	integer	Volume crawling status; 0 - crawled, 1 - not crawled
Dt	array	An array of dates and positions (dates in format "YYYYMMDD")
Be	array	Ranking at the beginning of the specified period
Fi	array	Ranking at the end of the specified period
Diff	array	The difference in rankings over the specified period
Diff1	array	The difference in rankings compared to the previous day
Diff7	array	The difference in rankings over a one week period
Diff30	array	The difference in rankings over a one month period
Vi	array	Domain's visibility on the specified date
Sf	array	Serp features present on SERP for the specified date
Tr	array	Estimated traffic on the specified date
Tc	array	Estimated traffic cost on the specified date
Lu	array	Landing URLs
Lt	array	Ranking type org: Organic adt: AdWords top adb: AdWords bottom

Organic Competitors Discovery report

tracking_competitors_organic

Price 1000 API units per line

This request lists the domains that appear in Google’s top 100 organic search results for the keywords from a tracking campaign for the chosen location, the average position and visibility for these domains.

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_type*	rootdomain subdomain subfolder url	Type of competitors' URLs
black_list	string	Exclude domains from the report output (separated by the '\|' symbol)
top_start	integer	The top of the position range to search for competitors on SERP
top_end	integer	The bottom of the position range to search for competitors on SERP
date_begin	Date in YYYYMMDD format	Start date of the selected period
date_end	Date in YYYYMMDD format	End date of the selected period
display_limit	integer	The number of returned results, the default value is 10
display_offset	integer	The number of lines to skip in the report output
display_sort	av_asc av_desc cd_asc cd_desc cl_asc cl_asc {DATE}_asc {DATE}_desc ur_asc ur_desc	Report sorting
linktype_filter	0 - Include local pack and hotels rankings. This is the default value 1 - Include only local pack and hotels rankings (organic rankings are excluded) 2 - Exclude local pack rankings 524288 - Exclude hotels rankings 524290 - Exclude local pack and hotels rankings	Specifies whether the local pack and hotels rankings should be included in the report output or excluded from it
use_volume	national regional local	Specifies the level of CPC and volume to be used in the report. If omitted, the bottom-most available level is used
business_name	string	The business name associated with the domain. It should match that from the Google My Business profile
serp_feature_filter	fsn: Featured snippet geo: Local pack hot: Hotels kng: Knowledge panel rev: Reviews amp: AMP stl: Site links vid: Video vib: Featured video new: Top stories rel: People also ask img: Images twt: Twitter knw: Instant answer flg: Flights shp: Shopping ads adt: AdWords top adb: AdWords bottom	Filters the report output for keywords that have a specific SERP feature on SERP

Fields marked by an asterisk (*) are required

Request example

GET /?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&action=report&type=tracking_competitors_organic&date_begin=20210518&date_end=20210524&top_start=1&top_end=10&url_type=rootdomain&linktype_filter=0&display_sort=20210524_desc

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example


{
    total: 560,
    state: "0",
    limit: 100,
    offset: 0,
    keywords_count: 200,
    data: {
		0: {
			Dt: {
				20210518: {
					Mc: 0,
					Av: 100,
					Sq: 0,
					Cl: 0,
					Sov: 0,
					Tr: "n/a",
					Tc: "n/a"
				},
				20210524: {
					Mc: 1,
					Av: 99.545,
					Sq: 6,
					Cl: 0.04120879120879121,
					Sov: 0.000013038870213554158,
					Tr: 8.1,
					Tc: 9.072
				},
				Diff: {
					Mc: 1,
					Av: -0.455,
					Sq: 6,
					Cl: 0.04120879120879121,
					Sov: 0.000013038870213554158,
					Tr: 8.1,
					Tc: 9.072
				}
			},
			Cd: 0.04120879120879121,
			Ur: "android.com"
		},
	...
	}
}

Return values

Name	Value	Description
total	integer	The number of results
limit	integer	The number of returned results
offset	integer	The number of lines to skip in the report output
keywords_count	integer	The number of keywords used to build this report
data	array	An array of competitor domains and their metrics
Dt	array	Dates and positions (Date in YYYYMMDD format)
Mc	integer	The number of keywords
Av	float	Average position
Sq	integer	Position deviation
Cl	float	Visibility
Sov	float	Share of Voice
Tr	float	Estimated traffic on the specified date
Tc	float	Estimated traffic cost on the specified date
Cd	float	Visibility change over the specified period
Ur	string	Competitor URL

AdWords Competitors Discovery report

tracking_competitors_adwords

Price 1000 API units per line

This request lists the domains that appear in Google’s paid search results for the keywords from a tracking campaign for the chosen location, the average position and visibility for these domains.

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_type*	rootdomain subdomain subfolder url	Type of competitors' URLs
black_list	string	Exclude domains from the report output (separated by the '\|' symbol)
top_start	integer	The top of the position range to search for competitors on SERP
top_end	integer	The bottom of the position range to search for competitors on SERP
date_begin	Date in YYYYMMDD format	Start date of the selected period
date_end	Date in YYYYMMDD format	End date of the selected period
display_limit	integer	The number of returned results, the default value is 10
display_offset	integer	The number of lines to skip in the report output
display_sort	av_asc av_desc cd_asc cd_desc cl_asc cl_asc {DATE}_asc {DATE}_desc ur_asc ur_desc	Report sorting

Fields marked by an asterisk (*) are required

Request example

GET /?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&action=report&type=tracking_competitors_adwords&date_begin=20210518&date_end=20210524&top_start=1&top_end=10&url_type=rootdomain&display_sort=20210524_desc

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example


{
    total: 45,
    state: "0",
    limit: 10,
    offset: 0,
    keywords_count: 200,
    data: {
		0: {
			Dt: {
				20210518: {
					Mc: 22,
					Av: 10.8,
					Sq: 3,
					Cl: 11,
					Sov: 1.0137587446283074,
					Tr: 629766.6666666666,
					Tc: 687222.3333333335
				},
				20210524: {
					Mc: 16,
					Av: 11.13,
					Sq: 2,
					Cl: 8,
					Sov: 0.8335755093315385,
					Tr: 517833.3333333334,
					Tc: 515993.66666666657
				},
				Diff: {
					Mc: -6,
					Av: 0.33,
					Sq: 0,
					Cl: -3,
					Sov: -0.1801832352967689,
					Tr: -111933.33333333326,
					Tc: -171228.66666666692
				}
			},
			Cd: -3,
			Ur: "apple.com"
		},
	...
	}
}

Return values

Name	Value	Description
total	integer	The number of results
limit	integer	The number of returned results
offset	integer	The number of lines to skip in the report output
keywords_count	integer	The number of keywords used to build this report
data	array	An array of competitor domains and their metrics
Dt	array	Dates and positions (Date in YYYYMMDD format)
Mc	integer	The number of keywords
Av	float	Average position
Sq	integer	Position deviation
Cl	float	Visibility
Sov	float	Share of Voice
Tr	float	Estimated traffic on the specified date
Tc	float	Estimated traffic cost on the specified date
Cd	float	Visibility change over the specified period
Ur	string	Competitor URL

Organic Visibility Index report

tracking_visibility_organic

Price 100 API units per request

This request returns a domain’s visibility and visibility changes over the 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	Start date of the selected period
date_end	Date in YYYYMMDD format	End date of the selected period
display_tags	string	Tags, separated by the '\|' symbol. The '-' sign can be used to exclude a tag. If only the included tags are present in the expression, then the OR logic is used to group them. If both included and excluded tags are present, then each category is grouped using the OR logic, but then the AND logic is used to join the categories
linktype_filter	0 - Include local pack and hotels rankings. This is the default value 1 - Include only local pack and hotels rankings (organic rankings are excluded) 2 - Exclude local pack rankings 524288 - Exclude hotels rankings 524290 - Exclude local pack and hotels rankings	Specifies whether the local pack and hotels rankings should be included in the report output or excluded from it
use_volume	national regional local	Specifies the level of CPC and volume to be used in the report. If omitted, the bottom-most available level is used
business_name	string	The business name associated with the domain. It should match that from the Google My Business profile
serp_feature_filter	fsn: Featured snippet geo: Local pack hot: Hotels kng: Knowledge panel rev: Reviews amp: AMP stl: Site links vid: Video vib: Featured video new: Top stories rel: People also ask img: Images twt: Twitter knw: Instant answer flg: Flights shp: Shopping ads adt: AdWords top adb: AdWords bottom	Filters the report output for keywords that have a specific SERP feature on SERP

Fields marked by an asterisk (*) are required

Request example

GET /?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&action=report&type=tracking_visibility_organic&date_begin=20210518&date_end=20210524&url=*.apple.com%2F*&linktype_filter=0

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example

{
    total: "7",
    state: "0",
    data: {
		0: {
			Dt: "20210518",
			Vi: 33397900,
			Vr: 45.8762,
			Av: 8.075,
			Sov: 5.89,
			Tr: 3258225.0324,
			Tc: 9745148.8893
		},
		...
		6: {
			Dt: "20210524",
			Vi: 32230100,
			Vr: 44.2721,
			Av: 8.165,
			Sov: 5.55,
			Tr: 3230495.1761,
			Tc: 9866793.9995
		}
    }
}

Return values

Name	Value	Description
total	integer	The number of results
data	array	An array of dates and a domain's metrics on them
Dt	Date in YYYYMMDD format	Date
Vi	float	Absolute visibility value
Vr	float	Relative visibility value
Av	float	Average position
Sov	float	Share of Voice
Tr	float	Estimated traffic on the specified date
Tc	float	Estimated traffic cost on the specified date

AdWords Visibility Index report

tracking_visibility_adwords

Price 100 API units per request

This report returns a domain’s visibility and visibility changes over the 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	Start date of the selected period
date_end	Date in YYYYMMDD format	End date of the selected period
display_tags	string	Tags, separated by the '\|' symbol. The '-' sign can be used to exclude a tag. If only the included tags are present in the expression, then the OR logic is used to group them. If both included and excluded tags are present, then each category is grouped using the OR logic, but then the AND logic is used to join the categories

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=*.apple.com%2F*

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example

{
    total: "7",
    state: "0",
    data: {
		0: {
			Dt: "20210518",
			Vi: 23000000,
			Vr: 11.5,
			Av: 10.745,
			Sov: 1.11,
			Tr: 690766.666,
			Tc: 815932.3328
		},
		...
		6: {
			Dt: "20210524",
			Vi: 16000000,
			Vr: 8,
			Av: 11.13,
			Sov: 0.83,
			Tr: 517833.3329,
			Tc: 515993.6663
		}
    }
}

Return values

Name	Value	Description
total	integer	The number of results
data	array	An array of dates and a domain's metrics on them
Dt	Date in YYYYMMDD format	Date
Vi	float	Absolute visibility value
Vr	float	Relative visibility value
Av	float	Average position
Sov	float	Share of Voice
Tr	float	Estimated traffic on the specified date
Tc	float	Estimated traffic cost on the specified date

Organic Landing Pages report

tracking_landing_pages_organic

Price 1000 API units per line

This request lists all URLs from the Google's top 100 search results that the specified domain appears in for the keywords from the tracking campaign.

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	Start date of the selected period
date_end	Date in YYYYMMDD format	End date of the selected period
display_tags	string	Tags, separated by the '\|' symbol. The '-' sign can be used to exclude a tag. If only the included tags are present in the expression, then the OR logic is used to group them. If both included and excluded tags are present, then each category is grouped using the OR logic, but then the AND logic is used to join the categories
display_filter	string	Filter for columns Ph, Nq, Cp
display_limit	integer	The number of returned results, the default value is 10
display_offset	integer	The number of lines to skip in the report output
display_sort	0_mc_asc 0_mc_desc 1_mc_asc 1_mc_desc md_asc md_desc 0_tr_asc 0_tr_desc 1_tr_asc 1_tr_desc trdiff_asc trdiff_desc 0_av_asc 0_av_desc 1_av_asc 1_av_desc ad_asc ad_desc 0_nq_asc 0_nq_desc 1_nq_asc 1_nq_desc rd_asc rd_desc	Report sorting
newlost_filter	new lost	Return only new or lost urls
linktype_filter	0 - Include local pack and hotels rankings. This is the default value 1 - Include only local pack and hotels rankings (organic rankings are excluded) 2 - Exclude local pack rankings 524288 - Exclude hotels rankings 524290 - Exclude local pack and hotels rankings	Specifies whether the local pack and hotels rankings should be included in the report output or excluded from it
use_volume	national regional local	Specifies the level of CPC and volume to be used in the report. If omitted, the bottom-most available level is used

Fields marked by an asterisk (*) are required

Request example

GET /?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&action=report&type=tracking_landing_pages_organic&date_begin=20210518&date_end=20210524&url=*.apple.com%2F*&linktype_filter=0&display_sort=1_mc_desc

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example


{
	total: 310,
	state: "0",
	limit: 100,
	offset: 0,
	new: 34,
	lost: 32,
	keywords: 200,
	Pc: {
	  http: 2,
	  https: 308
	},
	data: {
	  0: {
		  Ur: "https://apps.apple.com/us/app/zillow-real-estate-rentals/id310738695",
		  Tp: "",
		  Dt: {
			  20210518: {
				  Mc: 1,
				  Av: 3,
				  Tr: 52566.666666666664,
				  Tc: 9987.666666666666,
				  Rq: 16600000
			  },
			  20210524: {
				  Mc: 1,
				  Av: 4,
				  Tr: 43713.333333333336,
				  Tc: 8305.533333333333,
				  Rq: 16600000
			  },
			  Diff: {
				  Mc: 0,
				  Av: -1,
				  Tr: -8853.333333333328,
				  Tc: -1682.1333333333332,
				  Rq: 0
			  }
		  },
		  Kw: [
				  {
					  Pi: "5243708147689083041",
					  Ph: "zillow",
					  Tp: "",
					  Rq: 16600000,
					  Gs: 1,
					  Tg: { },
					  Dt: {
						  20210518: 3,
						  20210524: 4,
						  Diff: -1
					  },
					  Tr: {
						  20210518: 52566.666666666664,
						  20210524: 43713.333333333336,
						  Diff: -8853.333333333328
					  },
					  Tc: {
						  20210518: 9987.666666666666,
						  20210524: 8305.533333333333,
						  Diff: -1682.1333333333332
					  },
					  Lt: {
						  20210518: [
							"rev"
						  ],
						  20210524: [
							"rev"
						  ]
					  }
				  }
		  ],
		  Amp: 0
	  },
	...
}

Return values

Name	Value	Description
total	integer	The number of results
limit	integer	The number of returned results
offset	integer	The number of lines to skip in the report output
new	integer	The number of new URLs (URLs that didn't rank for any keyword on the start date of the selected period, but rank for at least one keyword on the end date of the selected period)
lost	integer	The number of lost URLs (URLs that ranked for at least one keyword on the start date of the selected period, but don't rank for any keyword on the end date of the selected period)
keywords	integer	The number of keywords used to build this report
Pc	integer	The number of http and https URLs
data	array	An array of landing URLs and their metrics
Ur	string	The URL that the keyword ranks for
Tp	new lost	"new" - the URL didn't rank for any keyword on the start date of the selected period, but ranks for at least one keyword on the end date of the selected period "lost" - the URL ranked for at least one keyword on the start date of the selected period, but doesn't rank for any keyword on the end date of the selected period
Mc	integer	The number of keywords the URL ranks for on the specified date
Av	float	The average position for the keywords the URL ranks for on the specified date
Tr	float	Estimated traffic on the specified date
Tc	float	Estimated traffic cost on the specified date
Rq	integer	Total volume for the keywords the URL ranks for on the specified date
Kw	array	A list of keywords the URL ranks for
Pi	string	Keyword ID
Ph	string	A keyword the URL ranks for
Kw -> Tp	new lost	"new" - the 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" - the 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>
Rq	integer	Keyword volume
Gs	integer	Volume crawling status; 0 - crawled, 1 - not crawled
Tg	array	Keyword tags
Kw -> Dt	array	An array of dates and positions
Lt	array	Ranking type org: Organic fsn: Featured snippet geo: Local pack hot: Hotels kng: Knowledge panel rev: Reviews amp: AMP stl: Site links vid: Video vib: Featured video new: Top stories rel: People also ask img: Images twt: Twitter knw: Instant answer flg: Flights shp: Shopping ads adt: AdWords top adb: AdWords bottom

Adwords Landing Pages report

tracking_landing_pages_adwords

Price 1000 API units per line

This request lists all URLs from the Google paid search results that the specified domain appears in for the keywords from the tracking campaign.

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	Start date of the selected period
date_end	Date in YYYYMMDD format	End date of the selected period
display_tags	string	Tags, separated by the '\|' symbol. The '-' sign can be used to exclude a tag. If only the included tags are present in the expression, then the OR logic is used to group them. If both included and excluded tags are present, then each category is grouped using the OR logic, but then the AND logic is used to join the categories
display_filter	string	Filter for columns Ph, Nq, Cp
display_limit	integer	The number of returned results, the default value is 10
display_offset	integer	The number of lines to skip in the report output
display_sort	0_mc_asc 0_mc_desc 1_mc_asc 1_mc_desc md_asc md_desc 0_tr_asc 0_tr_desc 1_tr_asc 1_tr_desc trdiff_asc trdiff_desc 0_av_asc 0_av_desc 1_av_asc 1_av_desc ad_asc ad_desc 0_nq_asc 0_nq_desc 1_nq_asc 1_nq_desc rd_asc rd_desc	Report sorting
newlost_filter	new lost	Return only new or lost urls

Fields marked by an asterisk (*) are required

Request example

GET /?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&action=report&type=tracking_landing_pages_adwords&date_begin=20210518&date_end=20210524&url=*.apple.com%2F*&linktype_filter=0&display_sort=1_mc_desc

Response

Result	Code
Success	HTTP 200
Error	HTTP 400

Response example


{
	total: 4,
	state: "0",
	limit: 500,
	offset: 0,
	new: 0,
	lost: 2,
	keywords: 200,
	Pc: {
		http: 0,
		https: 3
	},
	data: {
		0: {
			Ur: "https://music.apple.com/",
			Tp: "lost",
			Dt: {
				20210518: {
					Mc: 1,
					Av: 1,
					Tr: 18333.333333333332,
					Tc: 30433.333333333332,
					Rq: 550000
				},
				20210524: {
					Mc: 0,
					Av: "-",
					Tr: 0,
					Tc: 0,
					Rq: 0
				},
				Diff: {
					Mc: -1,
					Av: -11,
					Tr: -18333.333333333332,
					Tc: -30433.333333333332,
					Rq: -550000
				}
			},
			Kw: [
					{
						Pi: "11540482552829684149",
						Ph: "apple music",
						Tp: "lost",
						Rq: 550000,
						Gs: 1,
						Tg: { },
						Dt: {
							20210518: 1,
							20210524: "-",
							Diff: -11
						},
						Tr: {
							20210518: 18333.333333333332,
							20210524: 0,
							Diff: -18333.333333333332
						},
						Tc: {
							20210518: 30433.333333333332,
							20210524: 0,
							Diff: -30433.333333333332
						},
						Lt: {
							20210518: [
								"adt"
							],
							20210524: [ ]
						}
					}
			],
			Amp: 0
		},
	...
	}
}

Return values

Name	Value	Description
total	integer	The number of results
limit	integer	The number of returned results
offset	integer	The number of lines to skip in the report output
new	integer	The number of new URLs (URLs that didn't rank for any keyword on the start date of the selected period, but rank for at least one keyword on the end date of the selected period)
lost	integer	The number of lost URLs (URLs that ranked for at least one keyword on the start date of the selected period, but don't rank for any keyword on the end date of the selected period)
keywords	integer	The number of keywords used to build this report
Pc	integer	The number of http and https URLs
data	array	An array of landing URLs and their metrics
Ur	string	The URL that the keyword ranks for
Tp	new lost	"new" - the URL didn't rank for any keyword on the start date of the selected period, but ranks for at least one keyword on the end date of the selected period "lost" - the URL ranked for at least one keyword on the start date of the selected period, but doesn't rank for any keyword on the end date of the selected period
Mc	integer	The number of keywords the URL ranks for on the specified date
Av	float	The average position for the keywords the URL ranks for on the specified date
Tr	float	Estimated traffic on the specified date
Tc	float	Estimated traffic cost on the specified date
Rq	integer	Total volume for the keywords the URL ranks for on the specified date
Kw	array	A list of keywords the URL ranks for
Pi	string	Keyword ID
Ph	string	A keyword the URL ranks for
Kw -> Tp	new lost	"new" - the 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" - the 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>
Rq	integer	Keyword volume
Gs	integer	Volume crawling status; 0 - crawled, 1 - not crawled
Tg	array	Keyword tags
Kw -> Dt	array	An array of dates and positions
Lt	array	Ranking type org: Organic adt: AdWords top adb: AdWords bottom

Sortings

Value	Description
ad_asc	By the difference in average position over the selected period, in ascending order
ad_desc	By the difference in average position over the selected period, in descending order
0_av_asc	By average position on the start date of the selected period, in ascending order
0_av_desc	By average position on the start date of the selected period, in descending order
1_av_asc	By average position on the end date of the selected period, in ascending order
1_av_desc	By average position on the end date of the selected period, in descending order
av_asc	By average position, in ascending order
av_desc	By average position, in descending order
{DOMAIN_N}_be_asc	By position at the start date of the selected period, in ascending order
{DOMAIN_N}_be_desc	By position at the start date of the selected period, in descending order
cd_asc	By visibility change, in ascending order
cd_desc	By visibility change, in descending order
cl_asc	By visibility, in ascending order
cl_desc	By visibility, in descending order
cp_asc	By CPC, in ascending order
cp_desc	By CPC, in descending order
{DATE}_asc	By date, in ascending order
{DATE}_desc	By date, in descending order
{DOMAIN_N}_di_asc	By position change, in ascending order
{DOMAIN_N}_di_desc	By position change, in descending order
{DOMAIN_N}_fi_asc	By position at the end date of the selected period, in ascending order
{DOMAIN_N}_fi_desc	By position at the end date of the selected period, in descending order
{DOMAIN_N}_pos_asc	By position at the end date of the selected period, in ascending order
{DOMAIN_N}_pos_desc	By position at the end date of the selected period, in descending order
0_mc_asc	By the number of keywords having a specific URL on SERP for the start date of the selected period, in ascending order
0_mc_desc	By the number of keywords having a specific URL on SERP for the start date of the selected period, in descending order
1_mc_asc	By the number of keywords having a specific URL on SERP for the end date of the selected period, in ascending order
1_mc_desc	By the number of keywords having a specific URL on SERP for the end date of the selected period, in descending order
md_asc	By the difference in the number of keywords having a specific URL on SERP over the selected period, in ascending order
md_desc	By the difference in the number of keywords having a specific URL on SERP over the selected period, in descending order
0_nq_asc	By volume on the start date of the selected period, in ascending order
0_nq_desc	By volume on the start date of the selected period, in descending order
1_nq_asc	By volume on the end date of the selected period, in ascending order
1_nq_desc	By volume on the end date of the selected period, in descending order
nq_asc	By volume, in ascending order
nq_desc	By volume, in descending order
ph_asc	By keyword, in ascending order
ph_desc	By keyword, in descending order
rd_asc	By the difference in volume over the selected period, in ascending order
rd_desc	By the difference in volume over the selected period, in descending order
0_tr_asc	By estimated traffic on the start date of the selected period, in ascending order
0_tr_desc	By estimated traffic on the start date of the selected period, in descending order
1_tr_asc	By estimated traffic on the end date of the selected period, in ascending order
1_tr_desc	By estimated traffic on the end date of the selected period, in descending order
trdiff_asc	By the difference in the estimated traffic over the selected period, in ascending order
trdiff_desc	By the difference in the estimated traffic over the selected period, in descending order
ur_asc	By URL, in ascending order
ur_desc	By URL, 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 a URL-encoded string that contains filters separated by "|" (maximum 25 filters).

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

Example: display_filter=+|Ph|Co|phone|+|Nq|Gt|10000|+|Cp|Gt|2
filters the report for keywords that contain the word "phone", have volume greater than 10000 and CPC greater than 2

The encoded variant of the example filter to add to a request: display_filter=%2B%7CPh%7CCo%7Cphone%7C%2B%7CNq%7CGt%7C10000%7C%2B%7CCp%7CGt%7C2

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	string	Value to filter for

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, when that issue was detected, as well as the URLs of affected pages. Works only for the last snapshot.

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	ID of the last snapshot
issueId*	integer	Issue ID
page	integer	Pagination. If not specified, the default value will be 1.
filter	string	Filters data. Add this parameter as many times as you need.
limit	integer	Limits data. If not specified, the default value will be 10.
sort	index_desc, index_asc targeturl_desc,targeturl_asc firstseen_desc, firstseen_asc dominteractivetime_desc, dominteractivetime_asc samplesize_desc, samplesize_asc tag_desc, tag_asc code_desc, code_asc val_desc, val_asc count_desc, count_asc resourcetype_desc, resourcetype_asc info_desc, info_asc infourl_desc, infourl_asc item_desc, item_asc fields_desc, fields_as	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

Filters

To apply a filter to a report, add the filter parameter with a URL-encoded string.

Filter string format: '[+-]|field|operator|value1;...;valueN'

Parameter	Values	Description
sign	"+" or "-"	Include or exclude
field	string	Filter by the specified field
operation	Bw, Ew, Eq, Co	Bw - begins with Ew - ends with Eq - equals Co - contains
values	string	List of values separated by ';'

Example filter string:'+|source_url|Co|semrush;site_audit'

If you want to apply a number of filters, keep adding the filter parameter. Example:

https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/snapshot/{snapshotId}/issue/{issueId}?filter={filter1}&filter={filter2}&filter={filter3}

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