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.
All API requests use such HTTP methods such as POST, PUT, GET or DELETE with JSON parameters and must contain your API Key.
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.
https://api.semrush.com/
https://api.semrush.com/management/v1/projects?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Name | Value | Description |
---|---|---|
key* | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page |
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"url": "mysite.com",
"tools": [],
"project_id": 643526670283248,
"project_name": "myproject"
}
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 |
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.
https://api.semrush.com/management/v1/projects/{id}?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Name | Value | Description |
---|---|---|
key* | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page | |
id* | Project ID |
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"url": "mysite.com",
"tools": [],
"project_id": 643526670283248,
"project_name": "myproject"
}
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 |
This request allows you to create a new project, which includes naming the project and choosing a domain.
https://api.semrush.com/management/v1/projects?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Name | Value | Description |
---|---|---|
key* | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page | |
project_name* | Name of a user's project. Forbidden characters are ~`!#%'^&*=[]\/{}|":<>? | |
url* | The domain of the project |
{"project_name":"myproject","url":"mysite.com"}
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"url": "mysite.com",
"tools": [],
"project_id": 643526670283248,
"project_name": "myproject"
}
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 |
This request allows you to update or change a project’s name.
https://api.semrush.com/management/v1/projects?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Name | Value | Description |
---|---|---|
key* | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page | |
project_id* | Project ID | |
project_name | Name of a user's project. Forbidden characters are ~`!#%'^&*=[]\/{}|":<>? |
{"project_id":643526670283248, "project_name":"my old project"}
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"url": "mysite.com",
"tools": [],
"project_id": 643526670283248,
"project_name": "my old project"
}
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 |
This request allows you to delete a project, including its all of tool campaigns.
https://api.semrush.com/management/v1/projects/{id}?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Name | Value | Description |
---|---|---|
key* | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page | |
id* | Project ID |
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
This request allows you to add keywords to track to an existing project and group them with tags.
https://api.semrush.com/management/v1/projects/{id}/keywords?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Name | Value | Description |
---|---|---|
key* | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page | |
id* | Project ID | |
keywords | Keywords | |
tags | Tags for a keyword |
{"keywords":[{"keyword":"seo", "tags":["seo"]},{"keyword":"seotool", "tags":["seo"]}]}
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"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"
}
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 |
This request allows you to remove tracked keywords from an existing project.
https://api.semrush.com/management/v1/projects/{id}/keywords?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Name | Value | Description |
---|---|---|
key* | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page | |
id* | Project ID | |
keywords | Keywords |
{"keywords":[{"keyword":"seo"},{"keyword":"seotool"}]}
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"url": "mysite.com",
"tools": [],
"project_id": 643526670283248,
"project_name": "my old project"
}
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 |
https://api.semrush.com/management/v1/projects/{id}/competitors?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Name | Value | Description |
---|---|---|
key* | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page | |
id* | Project ID | |
competitors | List of project competitors |
{"competitors":["yahoo.com"]}
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"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"
}
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 |
https://api.semrush.com/management/v1/projects/{id}/competitors?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Name | Value | Description |
---|---|---|
key* | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page | |
id* | Project ID | |
competitors | List of project competitors |
{"competitors":["bing.com","yahoo.com"]}
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"url": "mysite.com",
"tools": [],
"project_id": 643526670283248,
"project_name": "myproject"
}
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 |
This request allows you to apply up to 5 tags to your tracked keywords.
https://api.semrush.com/management/v1/projects/{id}/tags?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Name | Value | Description |
---|---|---|
key* | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page | |
id* | Project ID | |
keywords | Keywords | |
tags | Tags for a keyword |
[{"tag":"seo", "keywords":["search tool", "search engine"]}]
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"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"
}
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 |
This request allows you to remove tags from tracked keywords.
https://api.semrush.com/management/v1/projects/{id}/tags?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Name | Value | Description |
---|---|---|
key* | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page | |
id* | Project ID | |
keywords | Keywords | |
tag | Tags for a keyword |
[{"tag":"seo", "keywords":["search tool", "search engine"]}]
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"url": "mysite.com",
"tools": [],
"project_id": 643526670283248,
"project_name": "myproject"
}
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 |
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.
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.
Name | Value | Description |
---|---|---|
key* | XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page |
tracking_url_type* | one of: rootdomain, subdomain, subfolder, url | tracked URL's type |
tracking_url* | string | tracked URL |
country_id* | integer | country id |
region_id | integer | region id |
city_id | integer | city id |
weekly_notification* | 1 or 0 |
|
first_letter | 1 (default) or 0 |
|
timezone | integer | Time zone (crawling starts at 5am in a specified time zone) |
device | one of: desktop, phone, tablet | Target device |
POST /enable?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
{"tracking_url": "ebay.com", "tracking_url_type": "rootdomain", "country_id": "2840", "weekly_notification": "1", "device": "desktop"}
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
This request allows you to enable or disable weekly emails with project statistics.
Name | Value | Description |
---|---|---|
key* | XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page |
PUT /notifications?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
DELETE /notifications?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
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.
This request allows you to get a list of countries for which geolocation for a project can be chosen.
Name | Value | Description |
---|---|---|
key* | XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page |
GET /countries?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"0": {
"id": 2840,
"name": "United States"
},
"1": {
"id": 2124,
"name": "Canada"
},
"2": {
"id": 2826,
"name": "United Kingdom"
},
...
}
Name | Value | Description |
---|---|---|
id | integer | country id |
name | string | country name |
This request allows you to get a list of regions for which geolocation for a project can be chosen.
Name | Value | Description |
---|---|---|
key* | XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page |
country_id* | integer | country id |
GET /countries/{country_id}/regions?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"0": {
"id": 21133,
"name": "Alabama"
},
"1": {
"id": 21132,
"name": "Alaska"
},
"2": {
"id": 21136,
"name": "Arizona"
},
...
}
Name | Value | Description |
---|---|---|
id | integer | region id |
name | string | region name |
This request allows you to get a list of cities for which geolocation for a project can be chosen.
Name | Value | Description |
---|---|---|
key* | XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page |
country_id* | integer | country id |
region_id* | integer | region id |
GET /countries/{country_id}/regions/{region_id}/cities?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"0": {
"id": 1013370,
"name": "Ajo"
},
"1": {
"id": 1013371,
"name": "Alpine"
},
"2": {
"id": 1013372,
"name": "Amado"
},
...
}
Name | Value | Description |
---|---|---|
id | integer | city id |
name | string | city name |
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/ |
This request returns a list of dates for which a campaign was collected.
Name | Value | Description |
---|---|---|
key* | XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page |
action* | report | |
type* | tracking_campaign_dates | request type |
GET /?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&action=report&type=tracking_campaign_dates
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"total": "9",
"last_crawl": "2",
"data": {
"0": {
"Dt": "20140401",
},
"1": {
"Dt": "20140402",
},
"2": {
"Dt": "20140403",
},
"3": {
"Dt": "20140404",
},
...
}
}
Name | Value | Description |
---|---|---|
total | integer | number of results |
last_crawl | integer | time since the last crawl |
Dt | date in YYYYMMDD format | date |
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.
Name | Value | Description |
---|---|---|
key* | XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page |
action* | report | |
type* | tracking_overview_organic | request type |
url* | string | tracked URL or competitor URL (with mask) |
display_tags | string | tags separated by the '|' symbol |
date_begin | date in YYYYMMDD format | starting date of a selected period |
date_end | date in YYYYMMDD format | end date of a selected period |
linktype_filter |
|
local pack filter |
serp_feature_filter |
|
Use this filter to see keywords that have certain SERP features on a SERP. |
GET /?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&action=report&type=tracking_overview_organic&date_begin=20140405&date_end=20140411&linktype_filter=0&url=*.ebay.com%2F*&serp_feature_filter=fsn
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"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": {}
}
Name | Value | Description |
---|---|---|
total | integer | number of results |
visibility | percentage | visibility index |
differenceVisibility | percentage | visibility index |
all | integer | The number of keywords that bring a domain to the top 100 search results |
all_difference | integer | changes in keywords that bring a domain to the top 100 search results |
all_improved | integer | The number of improved keywords that bring a domain to the top 100 search results |
all_declined | integer | The number of declined keywords that bring a domain to the top 100 search results |
all_left | integer | The number of keywords that no longer bring a domain to the top 100 search results |
all_entered | integer | The number of new keywords bringing a domain to the top 100 search results |
top3 | integer | number of keywords that bring a domain to the top 3 search results |
top3_improved | integer | The number of improved keywords that bring a domain to the top 3 search results |
top3_declined | integer | The number of declined keywords that bring a domain to the top 3 search results |
top3_difference | integer | changes in keywords that bring a domain to the top 3 search results |
top3_left | integer | The number of keywords that no longer bring a domain to the top 3 search results |
top3_entered | integer | The number of new keywords bringing a domain to the top 3 search results |
top10 | integer | number of keywords that bring a domain to the first page of search results |
top10_improved | integer | The number of improved keywords that bring a domain to the first page of search results |
top10_declined | integer | The number of declined keywords that bring a domain to the first page of search results |
top10_difference | integer | changes in keywords that bring a domain to the first page of search results |
top10_left | integer | The number of keywords that no longer bring a domain to the first page of search results |
top10_entered | integer | The number of new keywords bringing a domain to the first page of search results |
top20 | integer | number of keywords that bring a domain to the first two pages of search results |
top20_improved | integer | The number of improved keywords that bring a domain to the first two pages of search results |
top20_declined | integer | The number of declined keywords that bring a domain to the first two pages of search results |
top20_difference | integer | changes in keywords that bring a domain to the first two pages of search results |
top20_left | integer | The number of keywords that no longer bring a domain to the first two pages of search results |
top20_entered | integer | The number of new keywords bringing a domain to the first two pages of search results |
data | array | array of positions and numbers of keywords on this position (from 0 to 99) |
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.
Name | Value | Description |
---|---|---|
key* | XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page |
action* | report | |
type* | tracking_position_organic | request type |
top_filter | top_3, top_3_income, top_3_leave, top_3_down, top_3_up, top_1page, top_1page_income, top_1page_leave, top_1page_down, top_1page_up, top_2page, top_2page_income, top_2page_leave, top_2page_down, top_2page_up, top_100, top_100_income, top_100_leave, top_100_down, top_100_up | positions filter |
url* | string | tracked URL or competitor URL (with mask) |
date_begin | date in YYYYMMDD format | starting date of a selected period |
date_end | date in YYYYMMDD format | end date of a selected period |
display_tags | string | tags separated by the '|' symbol |
display_filter | string | filter for columns Ph, Nq, Cp |
display_limit | integer | number of returned results |
display_offset | integer | This parameter allows you to skip a specified number of lines before sending results |
display_sort | ph_asc, ph_desc, {DOMAIN_N}_pos_asc, {DOMAIN_N}_pos_desc, {DOMAIN_N}_be_asc, {DOMAIN_N}_be_desc, {DOMAIN_N}_di_asc, {DOMAIN_N}_di_desc, cp_asc, cp_desc, nq_desc, nq_asc | report sortings |
linktype_filter |
|
local pack filter |
serp_feature_filter |
|
Use this filter to see keywords that have certain SERP features on a SERP. |
GET /?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&action=report&type=tracking_position_organic&display_limit=10&display_offset=0&display_sort=20140411_asc&date_begin=20140405&date_end=20140411&display_filter=&url=*.ebay.com%2F*&linktype_filter=0&serp_filter_filter=fsn
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"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
}
},
...
}
Name | Value | Description |
---|---|---|
total | integer | number of results |
limit | integer | number of returned results |
offset | integer | This parameter allows you to skip a specified number of lines before sending results |
Pi | string | keyword ID |
Ph | string | keyword |
Tg | array | tags for a keyword |
Cp | integer | Average price in U.S. dollars advertisers pay for a user’s click on an ad containing the given keyword (Google AdWords). |
Nq | integer | The average number of times users have searched for a given keyword per month. We calculate this value over the last 12 months. |
Dt | array | array of dates and positions (dates in format "YYYYMMDD") |
Lt | string | Ranking type
|
Lu | array | Landing URLs |
Be | array | Position at the beginning of specified period |
Fi | array | Position at the end of specified period |
Sf | array | Serp features on a SERP in the specified date |
Vi | array | Visibility of domain on a SERP in the specified date |
Tr | array | Estimated traffic in the specified date |
Diff | array | Position difference for specified period |
Diff1 | array | Position difference for 1-day period |
Diff7 | array | Position difference for 1-week period |
Diff30 | array | Position difference for 1-month period |
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.
Name | Value | Description |
---|---|---|
key* | XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page |
action* | report | |
type* | tracking_position_adwords | request type |
url* | string | tracked URL or competitor URL (with mask) |
date_begin | date in YYYYMMDD format | starting date of a selected period |
date_end | date in YYYYMMDD format | end date of a selected period |
display_tags | string | tags separated by the '|' symbol |
display_filter | string | filter for columns Ph, Nq, Cp |
display_limit | integer | number of returned results |
display_offset | integer | This parameter allows you to skip a specified number of lines before sending results |
display_sort | ph_asc, ph_desc, {DOMAIN_N}_pos_asc, {DOMAIN_N}_pos_desc, {DOMAIN_N}_be_asc, {DOMAIN_N}_be_desc, {DOMAIN_N}_di_asc, {DOMAIN_N}_di_desc, cp_asc, cp_desc, nq_desc, nq_asc | report sortings |
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*
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"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
}
},
...
}
Name | Value | Description |
---|---|---|
total | integer | number of results |
limit | integer | number of returned results |
offset | integer | This parameter allows you to skip a specified number of lines before sending results |
Pi | string | keyword ID |
Ph | string | keyword |
Tg | array | tags for a keyword |
Cp | integer | Average price in U.S. dollars advertisers pay for a user’s click on an ad containing the given keyword (Google AdWords). |
Nq | integer | The average number of times users have searched for a given keyword per month. We calculate this value over the last 12 months. |
Dt | array | array of dates and positions (dates in format "YYYYMMDD") |
Lu | array | Landing URLs |
Be | array | Position at the beginning of specified period |
Fi | array | Position at the end of specified period |
Diff | array | Position difference for specified period |
Diff1 | array | Position difference for 1-day period |
Diff7 | array | Position difference for 1-week period |
Diff30 | array | Position difference for 1-month period |
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.
Name | Value | Description |
---|---|---|
key* | XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page |
action* | report | |
type* | tracking_competitors_organic | request type |
url | string | tracked URL |
url_type* | one of: rootdomain, subdomain, subfolder, url | type of a competitor URL |
black_list | string | exclude domains from results (separated by the '|' symbol) |
top_start | integer | start depth range |
top_end | integer | end depth range |
date_begin | date in YYYYMMDD format | starting date of a selected period |
date_end | date in YYYYMMDD format | end date of a selected period |
display_tags | string | tags separated by the '|' symbol |
display_limit | integer | number of returned results |
display_offset | integer | This parameter allows you to skip a specified number of lines before sending results |
display_sort | ur_asc, ur_desc, {DATE}_asc, {DATE}_desc, cl_asc, cl_desc, cd_asc, cd_desc, av_asc, av_desc | report sortings |
linktype_filter |
|
local pack filter |
serp_feature_filter |
|
Use this filter to see keywords that have certain SERP features on a SERP. |
GET /?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&action=report&type=tracking_competitors_organic&display_limit=10&display_offset=0&display_sort=20140411_desc&date_begin=20140405&date_end=20140411&top_start=1&top_end=10&url_type=rootdomain&linktype_filter=0&serp_feature_filter=fsn
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"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"
},
...
}
}
Name | Value | Description |
---|---|---|
total | integer | number of results |
limit | integer | number of returned results |
offset | integer | This parameter allows you to skip a specified number of lines before sending results |
Ur | string | competitor URL |
Dt | array | dates and positions (date in YYYYMMDD format) |
Cl | float | visibility |
Cd | float | visibility change for specified period |
Av | integer | average position |
Sq | integer | position deviation |
Mc | integer | number of keywords |
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.
Name | Value | Description |
---|---|---|
key* | XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page |
action* | report | |
type* | tracking_competitors_adwords | request type |
url | string | tracked URL |
url_type* | one of: rootdomain, subdomain, subfolder, url | type of a competitor URL |
black_list | string | exclude domains from results (separated by the '|' symbol) |
top_start | integer | start depth range |
top_end | integer | end depth range |
date_begin | date in YYYYMMDD format | starting date of a selected period |
date_end | date in YYYYMMDD format | end date of a selected period |
display_tags | string | tags separated by the '|' symbol |
display_limit | integer | number of returned results |
display_offset | integer | This parameter allows you to skip a specified number of lines before sending results |
display_sort | ur_asc, ur_desc, {DATE}_asc, {DATE}_desc, cl_asc, cl_desc, cd_asc, cd_desc, av_asc, av_desc | report sortings |
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
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"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"
},
...
}
}
Name | Value | Description |
---|---|---|
total | integer | number of results |
limit | integer | number of returned results |
offset | integer | This parameter allows you to skip a specified number of lines before sending results |
Ur | string | competitor URL |
Dt | array | dates and positions (date in YYYYMMDD format) |
Cl | float | visibility |
Cd | float | visibility change for specified period |
Av | integer | average position |
Sq | integer | position deviation |
Mc | integer | number of keywords |
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.
Name | Value | Description |
---|---|---|
key* | XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page |
action* | report | |
type* | tracking_visibility_organic | request type |
url* | string | tracked URL or competitor URL (with mask) |
date_begin | date in YYYYMMDD format | starting date of a selected period |
date_end | date in YYYYMMDD format | end date of a selected period |
display_tags | string | tags separated by the '|' symbol |
linktype_filter |
|
local pack filter |
GET /?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&action=report&type=tracking_visibility_organic&date_begin=20140401&date_end=20140411&url=*.ebay.com%2F*&linktype_filter=0
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"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
},
...
}
}
Name | Value | Description |
---|---|---|
total | integer | number of results |
Dt | date in YYYYMMDD format | date |
Vi | integer | absolute visibility value |
Vr | float | relative visibility value |
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.
Name | Value | Description |
---|---|---|
key* | XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page |
action* | report | |
type* | tracking_visibility_adwords | request type |
url* | string | tracked URL or competitor URL (with mask) |
date_begin | date in YYYYMMDD format | starting date of a selected period |
date_end | date in YYYYMMDD format | end date of a selected period |
display_tags | string | tags separated by the '|' symbol |
GET /?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&action=report&type=tracking_visibility_adwords&date_begin=20140401&date_end=20140411&url=*.ebay.com%2F*
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"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
},
...
}
}
Name | Value | Description |
---|---|---|
total | integer | number of results |
Dt | date in YYYYMMDD format | date |
Vi | integer | absolute visibility value |
Vr | integer | relative visibility value |
This report lists all landing pages of selected domain for current tracking campaign. For each landing page all the keywords that this landing page ranks for are reported.
Name | Value | Description |
---|---|---|
key* | XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page |
action* | report | |
type* | tracking_landing_pages_organic | request type |
url* | string | tracked URL or competitor URL (with mask) |
date_begin | date in YYYYMMDD format | starting date of a selected period |
date_end | date in YYYYMMDD format | end date of a selected period |
display_tags | string | tags separated by the '|' symbol |
display_filter | string | filter for columns Ph, Nq, Cp |
display_limit | integer | number of returned results |
display_offset | integer | This parameter allows you to skip a specified number of lines before sending results |
display_sort | ph_asc, ph_desc, {DOMAIN_N}_pos_asc, {DOMAIN_N}_pos_desc, {DOMAIN_N}_be_asc, {DOMAIN_N}_be_desc, {DOMAIN_N}_di_asc, {DOMAIN_N}_di_desc, cp_asc, cp_desc, nq_desc, nq_asc | report sortings |
newlost_filter | new, lost | return only new or lost urls |
linktype_filter |
|
local pack filter |
GET /?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&action=report&type=tracking_landing_pages_organic&display_sort=1_mc_desc&date_begin=20180207&date_end=20180207&display_limit=100&display_filter=&display_offset=0&display_tags=&url=semrush.com/blog&filter_url=&newlost_filter=&linktype_filter=0
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"total": 37,
"state": "0",
"limit": 100,
"offset": 0,
"new": 0,
"lost": 0,
"keywords": 107,
"Pc": {
"http": 0,
"https": 37
},
"data": {
"0": {
"Ur": "https://www.semrush.com/blog/topsy-is-dead-alternative-social-analytics-tools-you-need-to-use-now/",
"Tp": "",
"Dt": {
"20180207": {
"Mc": 9,
"Av": 2.22,
"Tr": 61.518333,
"Tc": 116.040433,
"Rq": 19620
},
"Diff": {
"Mc": 0,
"Av": 0,
"Tr": 0,
"Tc": 0,
"Rq": 0
}
},
"Kw": [
{
"Pi": "7922908393917093815",
"Ph": "topsy analytics",
"Tp": "",
"Rq": 320,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 1,
"Diff": 0
},
"Tr": {
"20180207": 3.882667,
"Diff": 0
},
"Tc": {
"20180207": 25.819733,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "1522738860508378941",
"Ph": "topsy com analytics",
"Tp": "",
"Rq": 170,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 1,
"Diff": 0
},
"Tr": {
"20180207": 2.062667,
"Diff": 0
},
"Tc": {
"20180207": 4.682253,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "3772292990852912364",
"Ph": "topsy social",
"Tp": "",
"Rq": 90,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 1,
"Diff": 0
},
"Tr": {
"20180207": 1.092,
"Diff": 0
},
"Tc": {
"20180207": 0,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "8747962949595138851",
"Ph": "topsy twitter analytics",
"Tp": "",
"Rq": 90,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 1,
"Diff": 0
},
"Tr": {
"20180207": 1.092,
"Diff": 0
},
"Tc": {
"20180207": 9.67512,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "9069259884330927019",
"Ph": "what is topsy com",
"Tp": "",
"Rq": 90,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 2,
"Diff": 0
},
"Tr": {
"20180207": 0.375,
"Diff": 0
},
"Tc": {
"20180207": 0,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "2019165307386841491",
"Ph": "topsy com",
"Tp": "",
"Rq": 5400,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 3,
"Diff": 0
},
"Tr": {
"20180207": 17.1,
"Diff": 0
},
"Tc": {
"20180207": 41.382,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "13769451381664187323",
"Ph": "topsy.com",
"Tp": "",
"Rq": 880,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 3,
"Diff": 0
},
"Tr": {
"20180207": 2.786667,
"Diff": 0
},
"Tc": {
"20180207": 2.870267,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "2409524746484837701",
"Ph": "topsy",
"Tp": "",
"Rq": 12100,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 4,
"Diff": 0
},
"Tr": {
"20180207": 31.863333,
"Diff": 0
},
"Tc": {
"20180207": 25.8093,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "3435076276275003494",
"Ph": "topsy twitter",
"Tp": "",
"Rq": 480,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 4,
"Diff": 0
},
"Tr": {
"20180207": 1.264,
"Diff": 0
},
"Tc": {
"20180207": 5.80176,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
}
],
"Amp": 0
},
...
}
Name | Value | Description |
---|---|---|
keywords | integer | number of keywords used to build this report |
limit | integer | maximum number of results to return |
offset | integer | use this parameter to specify how many results to skip before building a report |
total | integer | number of results |
lost | integer | number of lost URLs (URLs that ranked for at least one keyword from a given campaign on the start date of the selected period, but don't rank for any keyword from a given campaign on the end date of the selected period) |
new | integer | number of new URLs (URLs that didn't rank for any keyword from a given campaign on the start date of the selected period, but rank for at least one keyword from a given campaign on the end date of the selected period) |
data | array | list of URLs ranking for keywords from a given campaign |
data -> Ur | string | an URL that ranks for keyword(s) from a given campaign |
data -> Tp | string (can be “”, “new” or “lost”) | "new" - means that this URL didn't rank for any keyword from a given campaign on the start date of the selected period, but ranks for at least one keyword from a given campaign on the end date of the selected period. "lost" - means that this URL ranked for at least one keyword from a given campaign on the start date of the selected period, but doesn't rank for any keyword from a given campaign on the end date of the selected period. |
data -> Dt | array | data on overall metrics for a given URL |
data -> Dt -> YYYYMMDD | array | data on overall metrics for a given URL on a given date |
data -> Dt -> YYYYMMDD -> Av | float | average position for a list of keywords given URL ranks for on a given date |
data -> Dt -> YYYYMMDD -> Mc | integer | number of keywords given URL ranks for on a given date |
data -> Dt -> YYYYMMDD -> Rq | integer | total volume for a list of keywords given URL ranks for on a given date |
data -> Dt -> Diff | array | how values of overall metrics changed between the start and the end of the selected period |
data -> Dt -> Diff -> Av | float | how average position for a list of keywords given URL ranks for changed between the start and the end of the selected period |
data -> Dt -> Diff -> Mc | integer | how number of keywords given URL ranks for changed between the start and the end of the selected period |
data -> Dt -> Diff -> Rq | integer | how total volume changed between the start and the end of the selected period |
data -> Kw | array | list of keywords given URL ranks for |
data -> Kw -> Ph | string | keyword given URL ranks for |
data -> Kw -> Pi | string | keyword ID |
data -> Kw -> Rq | integer | keyword volume |
data -> Kw -> Tp | string (can be “”, “new” or “lost”) | "new" - means that this URL didn't rank for this keyword on the start date of the selected period, but ranks for this keyword on the end date of the selected period. "lost" - means that this URL ranked for this keyword on the start date of the selected period, but doesn't rank this keyword on the end date of the selected period. |
data -> Kw -> Tg | array | keyword tags |
data -> Kw -> Dt | array | data on overall metrics for a given pair: URL + keyword |
data -> Kw -> Dt -> Diff | integer | how position of a given URL, that ranks for given keyword on a given date changed between the start and the end of the selected period |
data -> Kw -> Lt | array | this array contains data on position type (organic or local map pack) |
data -> Kw -> Lt -> YYYYMMDD | string (can be “org” or “geo”) | what type of position URL held on the given day; “org” - normal organic position, “geo” - position within local map pack |
This report lists all landing pages of selected domain for current tracking campaign. For each landing page all the keywords that this landing page ranks for are reported.
Name | Value | Description |
---|---|---|
key* | XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page |
action* | report | |
type* | tracking_landing_pages_adwords | request type |
url* | string | tracked URL or competitor URL (with mask) |
date_begin | date in YYYYMMDD format | starting date of a selected period |
date_end | date in YYYYMMDD format | end date of a selected period |
display_tags | string | tags separated by the '|' symbol |
display_filter | string | filter for columns Ph, Nq, Cp |
display_limit | integer | number of returned results |
display_offset | integer | This parameter allows you to skip a specified number of lines before sending results |
display_sort | ph_asc, ph_desc, {DOMAIN_N}_pos_asc, {DOMAIN_N}_pos_desc, {DOMAIN_N}_be_asc, {DOMAIN_N}_be_desc, {DOMAIN_N}_di_asc, {DOMAIN_N}_di_desc, cp_asc, cp_desc, nq_desc, nq_asc | report sortings |
newlost_filter | new, lost | return only new or lost urls |
linktype_filter |
|
local pack filter |
GET /?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&action=report&type=tracking_landing_pages_adwords&display_sort=1_mc_desc&date_begin=20180207&date_end=20180207&display_limit=100&display_filter=&display_offset=0&display_tags=&url=semrush.com/blog&filter_url=&newlost_filter=&linktype_filter=0
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"total": 37,
"state": "0",
"limit": 100,
"offset": 0,
"new": 0,
"lost": 0,
"keywords": 107,
"Pc": {
"http": 0,
"https": 37
},
"data": {
"0": {
"Ur": "https://www.semrush.com/blog/topsy-is-dead-alternative-social-analytics-tools-you-need-to-use-now/",
"Tp": "",
"Dt": {
"20180207": {
"Mc": 9,
"Av": 2.22,
"Tr": 61.518333,
"Tc": 116.040433,
"Rq": 19620
},
"Diff": {
"Mc": 0,
"Av": 0,
"Tr": 0,
"Tc": 0,
"Rq": 0
}
},
"Kw": [
{
"Pi": "7922908393917093815",
"Ph": "topsy analytics",
"Tp": "",
"Rq": 320,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 1,
"Diff": 0
},
"Tr": {
"20180207": 3.882667,
"Diff": 0
},
"Tc": {
"20180207": 25.819733,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "1522738860508378941",
"Ph": "topsy com analytics",
"Tp": "",
"Rq": 170,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 1,
"Diff": 0
},
"Tr": {
"20180207": 2.062667,
"Diff": 0
},
"Tc": {
"20180207": 4.682253,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "3772292990852912364",
"Ph": "topsy social",
"Tp": "",
"Rq": 90,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 1,
"Diff": 0
},
"Tr": {
"20180207": 1.092,
"Diff": 0
},
"Tc": {
"20180207": 0,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "8747962949595138851",
"Ph": "topsy twitter analytics",
"Tp": "",
"Rq": 90,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 1,
"Diff": 0
},
"Tr": {
"20180207": 1.092,
"Diff": 0
},
"Tc": {
"20180207": 9.67512,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "9069259884330927019",
"Ph": "what is topsy com",
"Tp": "",
"Rq": 90,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 2,
"Diff": 0
},
"Tr": {
"20180207": 0.375,
"Diff": 0
},
"Tc": {
"20180207": 0,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "2019165307386841491",
"Ph": "topsy com",
"Tp": "",
"Rq": 5400,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 3,
"Diff": 0
},
"Tr": {
"20180207": 17.1,
"Diff": 0
},
"Tc": {
"20180207": 41.382,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "13769451381664187323",
"Ph": "topsy.com",
"Tp": "",
"Rq": 880,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 3,
"Diff": 0
},
"Tr": {
"20180207": 2.786667,
"Diff": 0
},
"Tc": {
"20180207": 2.870267,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "2409524746484837701",
"Ph": "topsy",
"Tp": "",
"Rq": 12100,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 4,
"Diff": 0
},
"Tr": {
"20180207": 31.863333,
"Diff": 0
},
"Tc": {
"20180207": 25.8093,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
},
{
"Pi": "3435076276275003494",
"Ph": "topsy twitter",
"Tp": "",
"Rq": 480,
"Gs": 1,
"Tg": {},
"Dt": {
"20180207": 4,
"Diff": 0
},
"Tr": {
"20180207": 1.264,
"Diff": 0
},
"Tc": {
"20180207": 5.80176,
"Diff": 0
},
"Lt": {
"20180207": [
"org"
]
}
}
],
"Amp": 0
},
...
}
Name | Value | Description |
---|---|---|
keywords | integer | number of keywords used to build this report |
limit | integer | maximum number of results to return |
offset | integer | use this parameter to specify how many results to skip before building a report |
total | integer | number of results |
lost | integer | number of lost URLs (URLs that ranked for at least one keyword from a given campaign on the start date of the selected period, but don't rank for any keyword from a given campaign on the end date of the selected period) |
new | integer | number of new URLs (URLs that didn't rank for any keyword from a given campaign on the start date of the selected period, but rank for at least one keyword from a given campaign on the end date of the selected period) |
data | array | list of URLs ranking for keywords from a given campaign |
data -> Ur | string | an URL that ranks for keyword(s) from a given campaign |
data -> Tp | string (can be “”, “new” or “lost”) | "new" - means that this URL didn't rank for any keyword from a given campaign on the start date of the selected period, but ranks for at least one keyword from a given campaign on the end date of the selected period. "lost" - means that this URL ranked for at least one keyword from a given campaign on the start date of the selected period, but doesn't rank for any keyword from a given campaign on the end date of the selected period. |
data -> Dt | array | data on overall metrics for a given URL |
data -> Dt -> YYYYMMDD | array | data on overall metrics for a given URL on a given date |
data -> Dt -> YYYYMMDD -> Av | float | average position for a list of keywords given URL ranks for on a given date |
data -> Dt -> YYYYMMDD -> Mc | integer | number of keywords given URL ranks for on a given date |
data -> Dt -> YYYYMMDD -> Rq | integer | total volume for a list of keywords given URL ranks for on a given date |
data -> Dt -> Diff | array | how values of overall metrics changed between the start and the end of the selected period |
data -> Dt -> Diff -> Av | float | how average position for a list of keywords given URL ranks for changed between the start and the end of the selected period |
data -> Dt -> Diff -> Mc | integer | how number of keywords given URL ranks for changed between the start and the end of the selected period |
data -> Dt -> Diff -> Rq | integer | how total volume changed between the start and the end of the selected period |
data -> Kw | array | list of keywords given URL ranks for |
data -> Kw -> Ph | string | keyword given URL ranks for |
data -> Kw -> Pi | string | keyword ID |
data -> Kw -> Rq | integer | keyword volume |
data -> Kw -> Tp | string (can be “”, “new” or “lost”) | "new" - means that this URL didn't rank for this keyword on the start date of the selected period, but ranks for this keyword on the end date of the selected period. "lost" - means that this URL ranked for this keyword on the start date of the selected period, but doesn't rank this keyword on the end date of the selected period. |
data -> Kw -> Tg | array | keyword tags |
data -> Kw -> Dt | array | data on overall metrics for a given pair: URL + keyword |
data -> Kw -> Dt -> Diff | integer | how position of a given URL, that ranks for given keyword on a given date changed between the start and the end of the selected period |
data -> Kw -> Lt | array | this array contains data on position type (organic or local map pack) |
data -> Kw -> Lt -> YYYYMMDD | string (can be “org” or “geo”) | what type of position URL held on the given day; “org” - normal organic position, “geo” - position within local map pack |
Value | Description |
---|---|
ph_asc | sorting by a keyword in ascending order (Ph) |
ph_desc | sorting by a keyword in descending order (Ph) |
{DATE}_asc | sorting by date in ascending order |
{DATE}_desc | sorting by date, in descending order |
cp_asc | sorting by CPC in ascending order (Cp) |
cp_desc | sorting by CPC in descending order (Cp) |
nq_asc | sorting by volume in ascending order (Nq) |
nq_desc | sorting by volume in descending order (Nq) |
{DOMAIN_N}_di_asc | sorting by the difference in a domain's previous and current positions in ascending order |
{DOMAIN_N}_di_desc | sorting by the difference in a domain's previous and current positions in descending order |
{DOMAIN_N}_fi_asc, {DOMAIN_N}_pos_asc | sorting by a position at the end date in ascending order |
{DOMAIN_N}_fi_desc, {DOMAIN_N}_pos_desc | sorting by a position at the end date in descending order |
{DOMAIN_N}_be_asc | sorting by a position at the starting date in ascending order |
{DOMAIN_N}_be_desc | sorting by a position at the starting date in ascending order |
ur_asc | sorting by a URL in ascending order |
ur_desc | sorting by a URL in descending order |
cl_asc | sorting by visibility in ascending order |
cl_desc | sorting by visibility in descending order |
cd_asc | sorting by visibility change in ascending order |
cd_desc | sorting by visibility change in descending order |
av_asc | sorting by average position in ascending order |
av_desc | sorting by average position in descending order |
{DATE} date in YYYYMMDD format
{DOMAIN_N} - domain number (0,1,2,3,4)
To apply a filter to the report, you should add the display_filter parameter with an URL-encoded string that contains filters separated by "|" (maximum number - 25).
A filter consists of <sign>|<field>|<operation>|<value>
Parameter | Values | Description |
---|---|---|
sign | "+" or "-" | include or exclude |
field | Ph, Cp, Nq |
|
operation | for metrical fields: Eq, Gt, Lt for textual fields: Bw, Ew, Eq, Co |
for metrical fields:
|
value | value to filter |
The base URL for all requests is:
https://api.semrush.com/management/v1/projects/{ID}/siteaudit
Where {ID} - id of the project
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.
https://api.semrush.com/management/v1/projects/{ID}/siteaudit/enable?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Name | Value | Description |
---|---|---|
key* | String | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page |
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"domain": "www.mysite.com",
"scheduleDay": 1,
"notify": false,
"allow": ["", "", ""],
"disallow": ["", "", ""],
"pageLimit": 1000,
"userAgentType": 2,
"removedParameters": ["", "", ""]
"crawlSubdomains": true,
"respectCrawlDelay": false
}
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:
|
removedParameters | Specifies URL parameters to be excluded from the audit scope |
crawlSubdomains | Specifies whether to crawl subdomains of the selected domain. Available values:
|
respectCrawlDelay | Specifies whether SEMrushBot should follow the “crawl-delay” directive in robots.txt. Available values:
|
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.
https://api.semrush.com/management/v1/projects/{ID}/siteaudit/save?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Name | Value | Description |
---|---|---|
key* | String | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page |
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"domain": "www.mysite.com",
"scheduleDay": 1,
"notify": false,
"allow": ["", "", ""],
"disallow": ["", "", ""],
"pageLimit": 1000,
"userAgentType": 2,
"removedParameters": ["", "", ""]
"crawlSubdomains": true,
"respectCrawlDelay": false
}
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:
|
removedParameters | Specifies URL parameters to be excluded from the audit scope |
crawlSubdomains | Specifies whether to crawl subdomains of the selected domain. Available values:
|
respectCrawlDelay | Specifies whether SEMrushBot should follow the “crawl-delay” directive in robots.txt. Available values:
|
The base URL for all requests is:
https://api.semrush.com/reports/v1/projects/{ID}/siteaudit
Where {ID} - id of the project
This request allows you to get a list of past audits' IDs, including the dates on which they were completed.
https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/snapshots?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Name | Value | Description |
---|---|---|
key* | String | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page |
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"snapshots":[
{
"snapshot_id":"540d9e420cf2e0c1006966e3",
"finish_date":1410178856809
},
{
"snapshot_id":"54102bd20cf2e0c100696a10",
"finish_date":1410345954754
}]
}
snapshot_id | Snapshot id |
finish_date | Date when the last audit finished |
This request allows you to get a description of why an issue could be harmful for a website and how it can be fixed.
https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/meta/issues?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Name | Value | Description |
---|---|---|
key* | String | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page |
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"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"
}]
}
id | Issue id |
title | Issue Title |
desc | Issue Description |
title_page | Page Title |
info_column | - |
count_description | - |
multidata | - |
other_problem_link | - |
desc_with_link | - |
This request allows you to run an audit.
https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/launch?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Name | Value | Description |
---|---|---|
key* | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page |
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"snapshot_id":"54102d92e4b0f889a040c9c8"
}
snapshot_id | Snapshot ID for this audit |
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.
https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/info?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Name | Value | Description |
---|---|---|
key* | String | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page |
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"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
}
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:
|
respectCrawlDelay | Indicates whether SEMrushBot followed the “crawl-delay” directive in robots.txt:
|
canonical | Indicates whether an analyzed page is marked with the rel=“canonical” link element |
user_agent_type | Type of user agent:
|
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 |
This request allows you to get an overview of an audit, including the website’s score, issues, its number of performed checks, etc.
https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/snapshot?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&snapshot_id={snapshot_id}
Name | Value | Description |
---|---|---|
key* | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page | |
snapshot_id | String | Snaphot Id, or latest snapshot |
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"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
}
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 |
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.
https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/snapshot/{snapshotId}/issue/{issueId}?page={page}&filter={filter}&sort={sort}&limit={limit}&key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Name | Value | Description |
---|---|---|
key* | string | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page |
snapshotId* | string | ID of the last snapshot |
issueId* | integer | Issue ID |
page | integer | Pagination. If not specified, the default value will be 1. |
filter | string | Filters data. Add this parameter as many times as you need. |
limit | integer | Limits data. If not specified, the default value will be 10. |
sort |
|
Sorting. |
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"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
}
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 | Date when an issue was first noticed
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 |
This request helps you get an ID of a crawled page.
https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/page/list?url_contains={url}&limit={limit}&key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Name | Value | Description |
---|---|---|
key* | String | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page |
url* | String | url for search(contains match) |
limit | integer default 10 | limit data line |
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"data":[
{
"url":"http://semrush.com",
"page_id":"54102d9e0cf2e0c100696c88"
},
],
"total":178
}
url | url |
page_id | page id |
total | Total number of results per request |
This request allows you to get information about a page, and to get a list of its issues.
https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/page/{pageId}?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Name | Value | Description |
---|---|---|
key* | String | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page |
pageId* | String | page ID |
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"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"
}
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 |
This request allows you to see audits’ results for a selected period.
https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/history?limit={limit}&offset={offset}&key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Name | Value | Description |
---|---|---|
key* | String | An identification key assigned to a user after subscribing to SEMrush that is available via Profile page |
limit* | Integer default 7 | limit |
offset* | Integer default 0 | offset |
Result | Code |
---|---|
Success | HTTP 200 |
Error | HTTP 400 |
{
"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
}
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 |
To apply a filter to a report, add the filter parameter with a URL-encoded string.
Filter string format: '[+-]|field|operator|value1;...;valueN'
Parameter | Values | Description |
---|---|---|
sign | "+" or "-" | Include or exclude |
field | string | Filter by the specified field |
operation | Bw, Ew, Eq, Co |
|
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}
Type | 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 | — |
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 |