logo-small

SEMrush API

Есть вопросы?
Клиенты из США, бесплатный звонок
+1-800-815-9959
не в сети
С понедельника по пятницу (ET)
Европейские клиенты, бесплатный звонок
United Kingdom
España
France
Italia
+44 (808) 1642570
в сети
С понедельника по пятницу по местному времени

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
 
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

NameValueDescription
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
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

NameValueDescription
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
 
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

NameValueDescription
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
 
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

NameValueDescription
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
 
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

NameValueDescription
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
 
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

NameValueDescription
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
 
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

NameValueDescription
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
 
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

NameValueDescription
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
 
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

NameValueDescription
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
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

NameValueDescription
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
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

NameValueDescription
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.

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

NameValueDescription
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
Price 100 API units per request

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

Request parameters

NameValueDescription
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_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

NameValueDescription
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

NameValueDescription
id integer Country ID
name string Country name
 
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

NameValueDescription
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

NameValueDescription
id integer Region ID
name string Region name
 
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

NameValueDescription
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

NameValueDescription
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.

 
tracking_campaign_dates
Price 100 API units per request

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

Request parameters

NameValueDescription
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

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

NameValueDescription
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

NameValueDescription
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
 
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

NameValueDescription
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

NameValueDescription
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 Средняя цена 1 клика по объявлению в (Google AdWords) по данному запросу для рекламодателя (в долларах США).
Nq integer Среднемесячное количество поисковых запросов по данному ключевому слову. Это значение рассчитывается за последние 12 месяцев.
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
 
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

NameValueDescription
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

NameValueDescription
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 Средняя цена 1 клика по объявлению в (Google AdWords) по данному запросу для рекламодателя (в долларах США).
Nq integer Среднемесячное количество поисковых запросов по данному ключевому слову. Это значение рассчитывается за последние 12 месяцев.
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
 
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

NameValueDescription
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

NameValueDescription
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
 
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

NameValueDescription
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

NameValueDescription
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
 
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

NameValueDescription
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

NameValueDescription
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
 
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

NameValueDescription
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

NameValueDescription
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
 
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

NameValueDescription
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

NameValueDescription
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
 
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

NameValueDescription
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

NameValueDescription
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
ValueDescription
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

ParameterValuesDescription
sign "+" or "-" Include or exclude
field
  • Ph
  • Cp
  • Nq
  • Ph - Phrase
  • Cp - Средняя цена 1 клика по объявлению в (Google AdWords) по данному запросу для рекламодателя (в долларах США).
  • Nq - Среднемесячное количество поисковых запросов по данному ключевому слову. Это значение рассчитывается за последние 12 месяцев.
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

 
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

NameValueDescription
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
 
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

NameValueDescription
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

 
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

NameValueDescription
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
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

NameValueDescription
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 -
 
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

NameValueDescription
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
 
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

NameValueDescription
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
 
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

NameValueDescription
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
 
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

NameValueDescription
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
 
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

NameValueDescription
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
 
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

NameValueDescription
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
 
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

NameValueDescription
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'

ParameterValuesDescription
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.
Тип Описание Стоимость в единицах API
на строку на вызов на ключевое слово
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