logo-small

SEMrush API

有任何问题?
美国客户,免费电话
+1-800-815-9959
offline
周一到周五 (ET)
欧洲客户,免费电话
United Kingdom
España
France
Italia
+44 (808) 1642570
offline
周一到周五 in your local time

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} - name of one of the available methods.

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
  • 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)
  • 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 tracking campaign creation is country_id. You can get a list of available countries and their corresponding regions and cities by sending these requests.

The base URL for all requests is:

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

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

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

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

Where {ID} - id of the project.

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

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

 
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 number of results
last_crawl integer time in hours 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
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 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
business_name string
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 number of results
visibility percentage visibility index
differenceVisibility percentage time since the last crawl
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 number of keywords that bring a domain to the top 3 search results
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 changes in keywords that bring a domain to the top 3 search results
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 number of keywords that bring a domain to 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 changes in keywords that bring a domain to 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 number of keywords that bring a domain to 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 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 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 array of positions and numbers of keywords on this position (from 0 to 99)
 
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
exclude domains from results (separated by the '|' symbol)
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
  • 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 sortings
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
use_volume
  • national
  • regional
  • local
business_name string
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
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 number of results
limit integer
offset integer This parameter allows you to skip a specified number of lines before sending results
data array
Pi string keyword ID
Ph string keyword
Kb string
Tg array positions filter
Cp float Average price in U.S. dollars advertisers pay for a user’s click on an ad containing the given keyword (Google AdWords).
Nq integer 每个月用户搜索特定关键词的平均次数。我们会根据最近 12 个月计算数值。
Gs integer
Dt array 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 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
  • 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 sortings
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 number of results
limit integer
offset integer This parameter allows you to skip a specified number of lines before sending results
data array
Pi string keyword ID
Ph string keyword
Kb string
Tg array positions filter
Cp float Average price in U.S. dollars advertisers pay for a user’s click on an ad containing the given keyword (Google AdWords).
Nq integer 每个月用户搜索特定关键词的平均次数。我们会根据最近 12 个月计算数值。
Gs integer
Dt array 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 a competitor URL
black_list string visibility change for specified period
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_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
  • av_asc
  • av_desc
  • cd_asc
  • cd_desc
  • cl_asc
  • cl_asc
  • {DATE}_asc
  • {DATE}_desc
  • ur_asc
  • ur_desc
report sortings
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
use_volume
  • national
  • regional
  • local
business_name string
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
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 number of results
limit integer
offset integer This parameter allows you to skip a specified number of lines before sending results
keywords_count integer
data array
Dt array dates and positions (date in YYYYMMDD format)
Mc integer
Av float position deviation
Sq integer number of keywords
Cl float average position
Sov float
Tr float Estimated traffic on the specified date
Tc float Estimated traffic cost on the specified date
Cd float visibility
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 a competitor URL
black_list string visibility change for specified period
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_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
  • av_asc
  • av_desc
  • cd_asc
  • cd_desc
  • cl_asc
  • cl_asc
  • {DATE}_asc
  • {DATE}_desc
  • ur_asc
  • ur_desc
report sortings
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 number of results
limit integer
offset integer This parameter allows you to skip a specified number of lines before sending results
keywords_count integer
data array
Dt array dates and positions (date in YYYYMMDD format)
Mc integer
Av float position deviation
Sq integer number of keywords
Cl float average position
Sov float
Tr float Estimated traffic on the specified date
Tc float Estimated traffic cost on the specified date
Cd float visibility
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 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 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
use_volume
  • national
  • regional
  • local
business_name string
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
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 number of results
data array
Dt date in YYYYMMDD format date
Vi float absolute visibility value
Vr float relative visibility value
Av float position deviation
Sov float
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 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=*.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 number of results
data array
Dt date in YYYYMMDD format date
Vi float absolute visibility value
Vr float relative visibility value
Av float position deviation
Sov float
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 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
  • 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 sortings
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
use_volume
  • national
  • regional
  • local
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 number of results
limit integer
offset integer This parameter allows you to skip a specified number of lines before sending results
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
Pc integer The number of http and https URLs
data array
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
Tg array positions filter
Kw -> Dt array 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 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
  • 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 sortings
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 number of results
limit integer
offset integer This parameter allows you to skip a specified number of lines before sending results
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
Pc integer The number of http and https URLs
data array
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
Tg array positions filter
Kw -> Dt array array of dates and positions
Lt array Ranking type
  • org: Organic
  • adt: AdWords top
  • adb: AdWords bottom
Sortings
ValueDescription
ad_asc
ad_desc
0_av_asc
0_av_desc
1_av_asc
1_av_desc
av_asc sorting by average position in ascending order
av_desc sorting by average position 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
cd_asc sorting by visibility change in ascending order
cd_desc sorting by visibility change in descending order
cl_asc sorting by visibility in ascending order
cl_desc sorting by visibility in descending order
cp_asc sorting by CPC in ascending order (Cp)
cp_desc sorting by CPC in descending order (Cp)
{DATE}_asc sorting by date in ascending order
{DATE}_desc sorting by date, in descending order
{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 sorting by a position at the end date in ascending order
{DOMAIN_N}_fi_desc sorting by a position at the end date in descending order
{DOMAIN_N}_pos_asc sorting by a position at the end date in ascending order
{DOMAIN_N}_pos_desc sorting by a position at the end date in descending order
0_mc_asc
0_mc_desc
1_mc_asc
1_mc_desc
md_asc
md_desc
0_nq_asc
0_nq_desc
1_nq_asc
1_nq_desc
nq_asc sorting by volume in ascending order (Nq)
nq_desc sorting by volume in descending order (Nq)
ph_asc sorting by a keyword in ascending order (Ph)
ph_desc sorting by a keyword in descending order (Ph)
rd_asc
rd_desc
0_tr_asc
0_tr_desc
1_tr_asc
1_tr_desc
trdiff_asc
trdiff_desc
ur_asc sorting by a URL in ascending order
ur_desc sorting by a 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 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 - Average price in U.S. dollars advertisers pay for a user’s click on an ad containing the given keyword (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
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.
类型 Description Cost in API units
per line per call per keyword
project_list List all existing projects 100
project_get Get information about an existing project 100
project_create Create a new project 100 100*
project_update Update an existing project 100 100*
project_delete Delete an existing project 100
project_add_keywords Add keywords to an existing project 100
project_delete_keywords Remove keywords from an existing project 100
project_add_competitors Add competitors to an existing project 100
project_delete_competitors Remove competitors from an existing project 100
project_add_tags Group keywords with tags in an existing project 100
project_remove_tags Remove tags from keywords in an existing project 100
tracking_overview_organic Organic Overview 100
tracking_visibility_organic Organic Visibility Index report 100
tracking_visibility_adwords AdWords Visibility Index report 100
tracking_position_organic Organic Positions report 100
tracking_position_adwords AdWords Positions report 100
tracking_competitors_organic Organic Competitors Discovery report 1000
tracking_competitors_adwords AdWords Competitors Discovery report 1000
tracking_landing_pages_organic Organic Landing Pages report 1000
tracking_landing_pages_adwords Adwords Landing Pages report 1000
tracking_campaign_dates Campaign Dates 100
tracking_enable Enable the Position Tracking Tool in a project 100
tracking_notification_update Enable/Disable email-sending containing project statistics 100
get_countries Get a list of countries 100
get_regions Get a list of regions 100
get_cities Get a list of cities 100
siteaudit_snapshot_list Get a list of a campaign's snapshots 100
siteaudit_meta Get text descriptions about issues 100
siteaudit_launch Run Audit 100
siteaudit_campaign_info Get information about a campaign 100
siteaudit_campaign_save Enable the Site Audit Tool 100
siteaudit_snapshot_info Get information about a snapshot 10000
siteaudit_snapshot_issue Detailed report for an issue 100 100
siteaudit_page_list Get page ID by an URL 100
siteaudit_page_info Get information about a page 1000
siteaudit_campaign_history Get snaphots history 10000** 10000
* The additional API units are charged for each new added keyword.
** By Snapshots
Error Messages

Projects API error messages are returned in a specific format:

{ "code": {ERROR_CODE}, "message": {ERROR_MESSAGE} }
ERROR_CODE integer Machine-parseable codes
ERROR_MESSAGE string Descriptive error text

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

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