logo-small

SEMrush API
3.0

¿Alguna pregunta?
Clientes de EE. UU., gratis
+1-855-814-4510
desconectado
Lunes hasta Viernes (ET)
Clientes Europeos, Gratis
United Kingdom
España
France
Italia
Россия
+34-900-838964
desconectado
Lunes hasta Viernes en tu zona horaria local

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, domain name, tracked keywords and competitors, as well as tools that have been activated for each project.

Endpoint

http://api.semrush.com/

Requested URL (GET)

http://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, domain name, tracked keywords and competitors, as well as tools that have been activated for this project.

Requested URL (GET)

http://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 plus 100 API units per keyword added

This request allows you to create a new project, which includes naming the project, choosing a domain, adding keywords to track and competitors, and grouping keywords with tags.

Requested URL (POST)

http://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
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 plus 100 API units per keyword added

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

Requested URL (PUT)

http://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
Fields marked by an asterisk (*) are required

Request example

{"project_id":643526670283248, "project_name":"my old project","competitors":["bing.com"]}

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)

http://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
Position Tracking Tool
Management

The base URL for all requests is:

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

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

Price 100 API units per request

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

Request parameters

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

Request example

POST /enable?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

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

Response

Result Code
Success HTTP 200
Error HTTP 400
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 tracking campaign creation is country_id. You can get a list of available countries and their corresponding regions and cities by sending these requests.

The base URL for all requests is:

http://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 allows you to get a list of countries for which geolocation for a project can be chosen.

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 allows you to get a list of regions for which geolocation for a project can be chosen.

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 allows you to get a list of cities for which geolocation for a project can be chosen.

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

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

Where {ID} - id of the project.

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

Url type Mask example
rootdomain *.ebay.com/*
subdomain www.ebay.com/*
subfolder ebay.com/motors/*
url http://www.ebay.com/motors/
URLs with a trailing slash (/) and those without this sign are different ones. The positions of these URLs may also differ in search engine results.

 
tracking_campaign_dates
Price 100 API units per request

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

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 number of results
last_crawl integer time since the last crawl
Dt date in YYYYMMDD format date
 
tracking_overview_organic
Price 100 API units per request

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

Request parameters

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
date_begin date in YYYYMMDD format starting date of a selected period
date_end date in YYYYMMDD format end date of a selected period
linktype_filter
  • 0 - Include local pack rankings in all reports. This is the default value.
  • 1 - Show only local pack rankings in all reports
  • 2 - Exclude local pack rankings from all reports
local pack filter
Fields marked by an asterisk (*) are required

Request example

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

Response

Result Code
Success HTTP 200
Error HTTP 400

Response example

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

Return values

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

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

Request parameters

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 tracked URL or competitor URL (with mask)
date_begin date in YYYYMMDD format starting date of a selected period
date_end date in YYYYMMDD format end date of a selected period
display_tags string tags separated by the '|' symbol
display_filter string filter for columns Ph, Nq, Cp
display_limit integer number of returned results
display_offset integer This parameter allows you to skip a specified number of lines before sending results
display_sort ph_asc, ph_desc, {DOMAIN_N}_pos_asc, {DOMAIN_N}_pos_desc, {DOMAIN_N}_be_asc, {DOMAIN_N}_be_desc, {DOMAIN_N}_di_asc, {DOMAIN_N}_di_desc, cp_asc, cp_desc, nq_desc, nq_asc report sortings
linktype_filter
  • 0 - Include local pack rankings in all reports. This is the default value.
  • 1 - Show only local pack rankings in all reports
  • 2 - Exclude local pack rankings from all reports
local pack filter
Fields marked by an asterisk (*) are required

Request example

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

Response

Result Code
Success HTTP 200
Error HTTP 400

Response example

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

Return values

NameValueDescription
total integer number of results
limit integer number of returned results
offset integer This parameter allows you to skip a specified number of lines before sending results
Pi string keyword ID
Ph string keyword
Tg array tags for a keyword
Cp integer Precio medio en la moneda seleccionada que los anunciantes pagan por clic de usuario en un anuncio que contiene una palabra clave determinada (Google AdWords).
Nq integer El promedio de veces que han buscado los usuarios una determinada palabra clave al mes. Este valor se calcula tomando como referencia los últimos 12 meses.
Dt array array of dates and positions (dates in format "YYYYMMDD")
Lt string Ranking type
  • "org" - organic ranking
  • "geo" - local pack ranking
Lu array Landing URLs
Be array Position at the beginning of specified period
Fi array Position at the end of specified period
Diff array Position difference for specified period
Diff1 array Position difference for 1-day period
Diff7 array Position difference for 1-week period
Diff30 array Position difference for 1-month period
 
tracking_position_adwords
Price 100 API units per line

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

Request parameters

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 tracked URL or competitor URL (with mask)
date_begin date in YYYYMMDD format starting date of a selected period
date_end date in YYYYMMDD format end date of a selected period
display_tags string tags separated by the '|' symbol
display_filter string filter for columns Ph, Nq, Cp
display_limit integer number of returned results
display_offset integer This parameter allows you to skip a specified number of lines before sending results
display_sort ph_asc, ph_desc, {DOMAIN_N}_pos_asc, {DOMAIN_N}_pos_desc, {DOMAIN_N}_be_asc, {DOMAIN_N}_be_desc, {DOMAIN_N}_di_asc, {DOMAIN_N}_di_desc, cp_asc, cp_desc, nq_desc, nq_asc report sortings
Fields marked by an asterisk (*) are required

Request example

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

Response

Result Code
Success HTTP 200
Error HTTP 400

Response example

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

Return values

NameValueDescription
total integer number of results
limit integer number of returned results
offset integer This parameter allows you to skip a specified number of lines before sending results
Pi string keyword ID
Ph string keyword
Tg array tags for a keyword
Cp integer Precio medio en la moneda seleccionada que los anunciantes pagan por clic de usuario en un anuncio que contiene una palabra clave determinada (Google AdWords).
Nq integer El promedio de veces que han buscado los usuarios una determinada palabra clave al mes. Este valor se calcula tomando como referencia los últimos 12 meses.
Dt array array of dates and positions (dates in format "YYYYMMDD")
Lu array Landing URLs
Be array Position at the beginning of specified period
Fi array Position at the end of specified period
Diff array Position difference for specified period
Diff1 array Position difference for 1-day period
Diff7 array Position difference for 1-week period
Diff30 array Position difference for 1-month period
 
tracking_competitors_organic
Price 1000 API units per line

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

Request parameters

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 string tracked URL
url_type* one of: rootdomain, subdomain, subfolder, url type of a competitor URL
black_list string exclude domains from results (separated by the '|' symbol)
top_start integer start depth range
top_end integer end depth range
date_begin date in YYYYMMDD format starting date of a selected period
date_end date in YYYYMMDD format end date of a selected period
display_tags string tags separated by the '|' symbol
display_limit integer number of returned results
display_offset integer This parameter allows you to skip a specified number of lines before sending results
display_sort ur_asc, ur_desc, {DATE}_asc, {DATE}_desc, cl_asc, cl_desc, cd_asc, cd_desc, av_asc, av_desc report sortings
linktype_filter
  • 0 - Include local pack rankings in all reports. This is the default value.
  • 1 - Show only local pack rankings in all reports
  • 2 - Exclude local pack rankings from all reports
local pack filter
Fields marked by an asterisk (*) are required

Request example

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

Response

Result Code
Success HTTP 200
Error HTTP 400

Response example

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

Return values

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

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

Request parameters

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 string tracked URL
url_type* one of: rootdomain, subdomain, subfolder, url type of a competitor URL
black_list string exclude domains from results (separated by the '|' symbol)
top_start integer start depth range
top_end integer end depth range
date_begin date in YYYYMMDD format starting date of a selected period
date_end date in YYYYMMDD format end date of a selected period
display_tags string tags separated by the '|' symbol
display_limit integer number of returned results
display_offset integer This parameter allows you to skip a specified number of lines before sending results
display_sort ur_asc, ur_desc, {DATE}_asc, {DATE}_desc, cl_asc, cl_desc, cd_asc, cd_desc, av_asc, av_desc report sortings
Fields marked by an asterisk (*) are required

Request example

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

Response

Result Code
Success HTTP 200
Error HTTP 400

Response example

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

Return values

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

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

Request parameters

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 starting date of a selected period
date_end date in YYYYMMDD format end date of a selected period
display_tags string tags separated by the '|' symbol
linktype_filter
  • 0 - Include local pack rankings in all reports. This is the default value.
  • 1 - Show only local pack rankings in all reports
  • 2 - Exclude local pack rankings from all reports
local pack filter
Fields marked by an asterisk (*) are required

Request example

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

Response

Result Code
Success HTTP 200
Error HTTP 400

Response example

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

Return values

NameValueDescription
total integer number of results
Dt date in YYYYMMDD format date
Vi integer absolute visibility value
Vr integer relative visibility value
 
tracking_visibility_adwords
Price 100 API units per request

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

Request parameters

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 starting date of a selected period
date_end date in YYYYMMDD format end date of a selected period
display_tags string tags separated by the '|' symbol
Fields marked by an asterisk (*) are required

Request example

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

Response

Result Code
Success HTTP 200
Error HTTP 400

Response example

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

Return values

NameValueDescription
total integer number of results
Dt date in YYYYMMDD format date
Vi integer absolute visibility value
Vr integer relative visibility value
Sortings
ValueDescription
ph_asc sorting by a keyword in ascending order (Ph)
ph_desc sorting by a keyword in descending order (Ph)
{DATE}_asc sorting by date in ascending order
{DATE}_desc sorting by date, in descending order
cp_asc sorting by CPC in ascending order (Cp)
cp_desc sorting by CPC in descending order (Cp)
nq_asc sorting by volume in ascending order (Nq)
nq_desc sorting by volume in descending order (Nq)
{DOMAIN_N}_di_asc sorting by the difference in a domain's previous and current positions in ascending order
{DOMAIN_N}_di_desc sorting by the difference in a domain's previous and current positions in descending order
{DOMAIN_N}_fi_asc, {DOMAIN_N}_pos_asc sorting by a position at the end date in ascending order
{DOMAIN_N}_fi_desc, {DOMAIN_N}_pos_desc sorting by a position at the end date in descending order
{DOMAIN_N}_be_asc sorting by a position at the starting date in ascending order
{DOMAIN_N}_be_desc sorting by a position at the starting date in ascending order
ur_asc sorting by a URL in ascending order
ur_desc sorting by a URL in descending order
cl_asc sorting by visibility in ascending order
cl_desc sorting by visibility in descending order
cd_asc sorting by visibility change in ascending order
cd_desc sorting by visibility change in descending order
av_asc sorting by average position in ascending order
av_desc sorting by average position in descending order

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

Filters

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

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

ParameterValuesDescription
sign "+" or "-" include or exclude
field Ph, Cp, Nq
  • Ph - phrase
  • Cp - Precio medio en la moneda seleccionada que los anunciantes pagan por clic de usuario en un anuncio que contiene una palabra clave determinada (Google AdWords).
  • Nq - El promedio de veces que han buscado los usuarios una determinada palabra clave al mes. Este valor se calcula tomando como referencia los últimos 12 meses.
operation for metrical fields: Eq, Gt, Lt
for textual fields: Bw, Ew, Eq, Co
for metrical fields:
  • Eq - exactly matching
  • Gt - greater than
  • Lt - less than
for textual fields:
  • Bw - starts with
  • Ew - ends with
  • Eq - exactly matching
  • Co - containing
value value to filter
Site Audit Tool
Management

The base URL for all requests is:

http://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)

http://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)

http://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:

http://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)

http://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)

http://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)

http://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)

http://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)

http://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, the date when this issue was detected, and lists of affected webpages’ URLS.

Requested URL (GET)

http://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 Snapshot Id
issueId* integer Issue Id
page integer default 1 Pagination
filter Filter data
limit integer default 10 limit data line
sort index_desc, index_asc, firstseen_desc, firstseen_asc Sorting
Fields marked by an asterisk (*) are required

Response

Result Code
Success HTTP 200
Error HTTP 400

Response example

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

Response parameters

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

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

Requested URL (GET)

http://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)

http://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)

http://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
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.
Tipo Descripción Coste en unidades de API
por línea por llamada por palabra clave
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_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
Have a Suggestion?